CQL 教程 - 网络与安全

24.1CQHttp 网络请求

CQHttp 基于 requests（同步）与 httpx（异步）的中文适配，覆盖 GET / POST / PUT / DELETE / PATCH / HEAD 全部常用方法，并提供会话复用与异步调用能力。

cql

从 cqhttp 导入 获取, 提交, 会话, 异步会话

# 同步请求
响应 = 获取("https://api.example.com/items", 参数={"页码": 1}, 超时=10)
print(响应.状态码, 响应.JSON())

# 会话：保持 Cookie 与请求头
with 会话() as 客户端:
    客户端.设置头({"Authorization": "Bearer xxx"})
    客户端.设置身份验证("用户名", "密码")
    响应 = 客户端.获取("https://api.example.com/me")

# 异步请求
async def 主():
    async with 异步会话() as 客户端:
        响应 = await 客户端.获取("https://api.example.com/me")
        print(响应.文本())

模块级函数

中文 API	说明
`获取(地址, 参数, 头, 超时)`	GET 请求
`提交(地址, ...)`	POST 请求
`更新(地址, ...)`	PUT 请求
`删除(地址, ...)`	DELETE 请求
`补丁(地址, ...)`	PATCH 请求
`头请求(地址, ...)`	HEAD 请求
`请求(方法, 地址, ...)`	指定方法的通用请求

公共参数：参数（查询串）、头（请求头）、JSON（JSON 请求体）、数据（表单体）、超时（秒）。

响应对象

中文 API	说明
`状态码` / `是否成功`	HTTP 状态码与请求是否成功
`头` / `地址`	响应头与最终请求地址
`文本()` / `内容()`	文本内容与二进制内容
`JSON()`	解析为 JSON 对象
`引发错误()`	请求失败时抛出异常

响应对象未定义的方法会自动转发到底层 requests / httpx 响应对象。

会话与异步会话

会话：同步会话，除模块级方法外支持 设置头()、设置身份验证(用户名, 密码)、关闭()，并支持 with 自动管理。
异步会话：异步会话，方法需要 await，支持 async with，适合高并发场景。

注意：HTTP 请求头（包括中文请求头的值）必须为 ASCII，含中文会抛 UnicodeEncodeError；HEAD 请求没有响应体，调用 JSON() / 文本() 会失败。

24.2CQSecurity 认证与加密

CQSecurity 基于 PyJWT 与 bcrypt，提供 JWT 令牌的签发与验证、密码的安全哈希与校验，是构建登录认证体系的常用组件。

cql

从 cqsecurity 导入 创建令牌, 验证令牌, 密码哈希, 验证密码, 过期令牌错误

密钥 = "0123456789abcdef0123456789abcdef"   # 建议 32 字节以上

# JWT 令牌
令牌 = 创建令牌({"用户": "小明", "角色": "管理员"}, 密钥, 过期秒=3600)
载荷 = 验证令牌(令牌, 密钥)
print(载荷["用户"])

# bcrypt 密码哈希
哈希 = 密码哈希("我的密码")
print(验证密码("我的密码", 哈希))    # 真
print(验证密码("错误密码", 哈希))    # 假

API 一览

中文 API	说明
`创建令牌(载荷, 密钥, 算法="HS256", 过期秒=None, 主题=None, 签发者=None, 受众=None)`	生成 JWT 令牌
`验证令牌(令牌, 密钥, 算法="HS256")`	验证并解码 JWT
`解码令牌(...)`	验证令牌的别名
`密码哈希(密码, 成本=12)`	bcrypt 密码哈希
`生成密码哈希(密码)`	密码哈希的别名
`验证密码(密码, 哈希)`	校验密码是否匹配
`密码校验(密码, 哈希)`	验证密码的别名

异常

过期令牌错误：令牌已过期。
无效令牌错误：令牌格式非法或无法解析。
无效签名错误：签名校验失败。
无效受众错误：受众（audience）不匹配。
无效签发者错误：签发者（issuer）不匹配。

注意：HS256 算法的密钥建议 32 字节以上，过短会触发 InsecureKeyLengthWarning 警告。

24.3CQConfig 配置管理

CQConfig 基于 python-dotenv，读取 .env 配置文件与系统环境变量，将密钥、地址等配置与代码分离。

cql

从 cqconfig 导入 加载, 读取, 环境

# 方式一：函数式
加载(".env", 覆盖=False)
地址 = 读取("数据库地址", "默认值")

# 方式二：环境对象
环境对象 = 环境(".env")
环境对象.获取("端口", 3306)       # 优先环境变量，其次 .env，最后默认值
环境对象.设置("临时键", "值")      # 仅当前进程
环境对象.是否存在("调试模式")
环境对象.全部()                    # 合并字典
环境对象.重新加载()                # 重新读取 .env

API 一览

中文 API	说明
`加载(路径=".env", 覆盖=False)`	载入环境变量
`读取(键, 默认=None)` / `获取(...)`	读取环境变量
`设置(键, 值)` / `删除(键)`	设置 / 删除（仅当前进程）
`全部()`	返回全部环境变量
`读取文件值(路径)`	仅读 .env 文件，不写入环境变量
`环境(路径)`	环境对象，提供上述对象方法

24.4CQLog 日志

CQLog 优先使用 loguru，未安装时自动回退标准库 logging，提供简洁的中文日志接口。

cql

从 cqlog 导入 配置, 信息, 调试, 警告, 错误, 致命, 获取日志器

配置("DEBUG")                          # 设置级别
信息("应用已启动，端口：{}", 8000)      # 支持 {} 占位

日志 = 获取日志器("我的应用")
日志.调试("调试细节")
日志.警告("警告信息")
日志.错误("出错了")

# loguru 模式可输出到文件
日志.添加文件("app.log", 级别="INFO")

级别常量

中文常量	对应级别
`调试`	DEBUG
`信息`	INFO
`警告`	WARNING
`错误`	ERROR
`致命`	CRITICAL

日志信息支持 {} 占位符，与 格式化 语法一致，可避免字符串拼接。