31 lines
1.1 KiB
Markdown
31 lines
1.1 KiB
Markdown
# 前端 API 契约检查
|
||
|
||
本仓库只包含 Next.js 前端，Python 后端仍在独立项目中维护。前端实际调用的
|
||
HTTP method 与 path 统一记录在
|
||
`src/data/services/api/api_contract.json`，`ApiPath` 与 OpenAPI 检查共同消费这份清单。
|
||
|
||
## 本地检查
|
||
|
||
传入 Python 后端生成的 OpenAPI JSON 文件或 URL：
|
||
|
||
```bash
|
||
pnpm contract:check ../backend/openapi.json
|
||
pnpm contract:check https://backend.example.com/openapi.json
|
||
```
|
||
|
||
也可以使用环境变量：
|
||
|
||
```bash
|
||
BACKEND_OPENAPI_SOURCE=https://backend.example.com/openapi.json pnpm contract:check
|
||
```
|
||
|
||
检查会验证前端依赖的每个 method/path 是否仍由后端公开。路径参数名称不同
|
||
（例如 `{albumId}` 与 `{album_id}`）不会产生误报。字段级兼容仍由前端 Zod
|
||
Schema 和 DTO 测试负责，避免仅凭 OpenAPI 生成代码覆盖现有防御性解析规则。
|
||
|
||
## CI 配置
|
||
|
||
在 Gitea Actions Secrets 中配置 `BACKEND_OPENAPI_SOURCE` 后，CI 会比较目标
|
||
Python 后端的实时 OpenAPI。未配置时 CI 会明确记录跳过原因，本地的比较器测试
|
||
仍会随 `pnpm quality` 执行。
|