REST API 命名约定实战指南

举报
yd_278762296 发表于 2026/11/12 06:25:50 2026/11/12
【摘要】 本文梳理 REST API 命名约定的核心原则:资源用复数名词、操作交给 HTTP 方法、路径用小写连字符、过滤分页走查询参数,并给出正反示例与可直接落地的团队执行建议。

为什么命名约定重要

URL 是 API 契约中最先被阅读的部分。命名混乱会让调用方反复查文档,命名一致则几乎可以猜出接口含义。约定本身没有绝对标准,关键是全团队统一并长期坚持。

核心原则:资源用名词,操作交给 HTTP 方法

URL 表示资源,HTTP 方法表示对资源的操作,不要把动词写进路径:

GET    /users          # 用户列表
POST   /users          # 创建用户
GET    /users/42       # 单个用户详情
PUT    /users/42       # 全量更新
PATCH  /users/42       # 部分更新
DELETE /users/42       # 删除

五条具体约定

  • 名词用复数:/users 而不是 /user,集合语义更清晰。
  • 路径用小写加连字符:/order-items,而不是 /orderItems 或 /order_items,避免大小写敏感带来的歧义。
  • 层级一般不超过两层:/users/42/orders 表示“某用户的订单”,更深的关联改用查询参数表达。
  • 过滤、分页用查询参数:GET /users?status=active&page=2&size=20,不要设计 /users/active/page/2 这类路径。
  • 版本号放路径最前面:如 /v1/users,出现不兼容变更时发布 /v2,并为旧版本明确废弃周期。
  • 动作类需求怎么办

    难以映射为增删改查的操作,把它建模成子资源。例如“禁用用户”不要写成动词式路径:

    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)

    0/1000
    抱歉,系统识别当前为高风险访问,暂不支持该操作

    全部回复

    上滑加载中

    设置昵称

    在此一键设置昵称,即可参与社区互动!

    *长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

    *长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。