15 lines
710 B
Markdown
15 lines
710 B
Markdown
---
|
||
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`。
|