REST API 命名约定实战指南
【摘要】 本文梳理 REST API 命名约定的核心原则:资源用复数名词、操作交给 HTTP 方法、路径用小写连字符、过滤分页走查询参数,并给出正反示例与可直接落地的团队执行建议。
为什么命名约定重要
URL 是 API 契约中最先被阅读的部分。命名混乱会让调用方反复查文档,命名一致则几乎可以猜出接口含义。约定本身没有绝对标准,关键是全团队统一并长期坚持。
核心原则:资源用名词,操作交给 HTTP 方法
URL 表示资源,HTTP 方法表示对资源的操作,不要把动词写进路径:
GET /users # 用户列表
POST /users # 创建用户
GET /users/42 # 单个用户详情
PUT /users/42 # 全量更新
PATCH /users/42 # 部分更新
DELETE /users/42 # 删除
五条具体约定
动作类需求怎么办
难以映射为增删改查的操作,把它建模成子资源。例如“禁用用户”不要写成动词式路径:
POST /users/42/disable # 动词式,不推荐
PUT /users/42/status # 推荐:把状态当作子资源,请求体传 {"status": "disabled"}
反例对照
# 不推荐 → 推荐
GET /getAllUsers → GET /users
POST /createUser → POST /users
GET /user/42/orderList → GET /users/42/orders
收尾建议
命名约定的价值在于执行。建议今天就基于以上规则整理一份团队 API 设计清单,在代码评审中逐条核对新增接口,先统一增量、再分批迁移存量,让约定真正沉淀为规范。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)