---
applyTo: "**/*.{py,md}"
description: "用于 API 设计与接口实现，关键词：REST、状态码、统一响应、OpenAPI、分页"
---

# API 设计约束

- REST 接口默认使用资源名词复数与语义化 HTTP 方法，禁止 URL 动词化。
- API 必须进行版本化（例如 `/api/v1/...`）。
- 响应结构统一为 `{code, msg, data}`，并返回可追踪请求标识（traceId 或等价字段）。
- 正确使用 HTTP 状态码，禁止“错误也返回 200”。
- 分页场景明确采用页码分页或游标分页，并在接口文档中说明。
- 所有对外接口需补齐 OpenAPI 注解与示例。
- 参考规范：`02 - Design Standard/2.2 API 接口设计规范.md`。