CQL 教程 - CQFastAPI Web 后端

21.1简介

CQFastAPI 是基于 FastAPI 的中文适配，用法与 FastAPI 完全一致，底层库为 fastapi + uvicorn。安装方式：

bash

cd cql-lang
pip install .[web]     # 安装 CQFastAPI：fastapi + uvicorn

应用对象 快速应用() 对应 FastAPI，支持标题、依赖等全部参数。
路由装饰器、参数声明、响应对象、异常与状态码常量均有中文别名。
可在 .cql 中文源码中使用，也可在普通 Python 中导入 cqfastapi。

21.2快速开始

参考 examples/web_hello.cql，一个完整的中文 Web 后端：

cql

# -*- coding: utf-8 -*-
# web_hello.cql
# 运行方式：cql run examples/web_hello.cql
# 然后浏览器访问：
#     http://127.0.0.1:8000/
#     http://127.0.0.1:8000/物品/42?名称=可爱

从 CQFastAPI 导入 快速应用, 查询参数, 路径参数, 启动服务
从 CQLog 导入 信息

应用 = 快速应用(标题="CQL Web 示例")

@应用.获取("/")
函数 首页():
    信息("访问了首页")
    返回 {"消息": "你好，CQL Web 世界！"}

@应用.获取("/物品/{id}")
函数 获取物品(id: 整数, 名称: 文本 = 查询参数(描述="物品名称")):
    返回 {"编号": id, "名称": 名称}

@应用.提交("/物品")
函数 创建物品(名称: 文本 = 查询参数(描述="物品名称")):
    返回 {"创建": 真, "名称": 名称}

如果 __name__ == "__main__":
    启动服务(应用, 端口=8000)

运行后浏览器访问：

http://127.0.0.1:8000/：返回首页 JSON {"消息": "你好，CQL Web 世界！"}。
http://127.0.0.1:8000/物品/42?名称=可爱：{id} 是路径参数，名称 是查询参数，返回 {"编号": 42, "名称": "可爱"}。

21.3路由装饰器

在 快速应用() 创建的应用对象上，用中文装饰器注册路由：

中文 API	底层	说明
`应用.获取(...)`	`get`	GET 请求
`应用.提交(...)`	`post`	POST 请求
`应用.更新(...)`	`put`	PUT 请求
`应用.删除(...)`	`delete`	DELETE 请求
`应用.部分更新(...)`	`patch`	PATCH 请求
`应用.选项路由(...)`	`options`	OPTIONS 请求
`应用.头路由(...)`	`head`	HEAD 请求
`应用.网络套接字路由(...)`	`websocket`	WebSocket 路由

其他常用应用方法：路由组(...)（APIRouter，支持前缀 / 标签）、应用.包含路由组(路由组)（include_router）、应用.添加中间件(...)、应用.挂载(...)、应用.异常处理(...)、应用.启动事件 / 关闭事件(函数)（on_event）。

21.4参数声明

路径函数的中文参数声明，均支持中文参数名（默认值、描述、标题、别名）：

中文 API	底层
`查询参数(描述=..., 默认值=...)`	`fastapi.Query`
`路径参数(...)`	`fastapi.Path`
`请求体(...)`	`fastapi.Body`
`请求头(...)`	`fastapi.Header`
`饼干(...)`	`fastapi.Cookie`
`表单(...)`	`fastapi.Form`
`文件(...)`	`fastapi.File`
`依赖(...)`	`fastapi.Depends`
`安全(...)`	`fastapi.Security`

配合中文类型注解使用：函数获取物品(id: 整数, 名称: 文本 = 查询参数(描述="物品名称"))，其中 id 是路径参数，名称 是带描述与默认值的查询参数。

21.5响应与异常

响应类：响应 / JSON响应 / HTML响应 / 文本响应 / 文件响应 / 重定向响应 / 流响应，对应 fastapi.responses.*。

异常：HTTP异常(状态码=500, 详情=None, 头=None)，对应 fastapi.HTTPException。配合中文状态码常量使用：

中文常量	值	含义
`成功`	200	请求成功
`创建成功`	201	资源创建成功
`错误请求`	400	请求参数错误
`未授权`	401	未认证
`禁止`	403	无权限
`未找到`	404	资源不存在
`内部服务器错误`	500	服务器内部错误

示例：校验路径参数并抛出中文异常：

cql

从 CQFastAPI 导入 快速应用, HTTP异常, 错误请求, 未找到

应用 = 快速应用()

@应用.获取("/物品/{id}")
函数 获取物品(id: 整数):
    如果 id <= 0:
        抛出 HTTP异常(状态码=错误请求, 详情="编号必须大于 0")
    如果 id > 100:
        抛出 HTTP异常(状态码=未找到, 详情="物品不存在")
    返回 {"编号": id}

21.6启动与注意事项

启动服务器使用 启动服务(应用, 端口=8000)，对应 uvicorn.run，还支持 主机、重载、日志级别 等参数：

cql

如果 __name__ == "__main__":
    启动服务(应用, 主机="0.0.0.0", 端口=8000, 重载=真)

注意：路径参数名必须用英文（如 {id}），中文参数名会导致路由 404；路径本身、函数名、查询参数名可以使用中文。

SQL 字符串（配合 CQSqlite）保持英文关键字。
跨域、压缩、可信主机中间件也有中文别名：跨域中间件（CORSMiddleware）、压缩中间件（GZipMiddleware）、可信主机中间件（TrustedHostMiddleware）。