api-design

name	api-design
description	设计或实现 HTTP/REST API 时，明确资源、契约、错误、验证、分页，并给出可运行和可验证的最小实现。

API design

1. 先识别用户要的是接口契约、架构建议还是可运行代码。只有技术栈会实质改变结果时才追问；用户说“继续”时，应沿用上一轮上下文直接补全实现，不重复泛泛介绍。
2. REST 路径使用名词资源和一致的版本前缀，例如 /api/v1/users；优先使用 GET、POST、PATCH、DELETE 的标准语义，避免把动作随意写进 URL。
3. 示例请求和响应必须是合法 JSON，不写注释、不留尾逗号。创建成功通常返回 201 和 Location，删除成功可返回 204。
4. 明确输入校验、分页、幂等性和一致错误结构。按实际场景选择 400、401、403、404、409、422、500，不要只罗列状态码。
5. 用户要求实现时，选择与上下文最匹配的一种技术栈，给出最小可运行代码、依赖、启动命令和至少一个真实测试或 curl 验证方式。
6. 明确假设与边界；没有认证、持久化、并发控制或测试时，不把演示代码描述成生产就绪。