【RESTful API】API设计 (http治理)

根据Google API设计指南整理的RESTful API示例，涵盖核心HTTP方法（GET、POST、PUT、PATCH、DELETE）及父子资源嵌套场景， 设计遵循以下原则：

1. 资源命名 ：使用名词复数形式（如/users），URI层级表达父子关系（如/users/{userId}/orders）

2. HTTP方法语义：

   • GET：查询资源
   • POST：创建资源
   • PUT：全量更新
   • PATCH：部分更新
   • DELETE：删除资源

3. 无状态性：每个请求包含完整上下文

4. 版本控制 ：URL中嵌入版本号（如/v1/）

Google API设计指南的核心技术要点整理，结合其官方规范及实践总结：

---

📌 一、设计原则

1. 面向资源设计 (Resource-Oriented Design)

   • API 的核心抽象是资源 （名词），通过标准方法 （动词）操作。资源以层次结构组织（如 users/{id}/messages/{id}），资源名称需为原子性字符串39。
   • 资源集合命名：复数小写驼峰式 （如 shelves），避免泛用词（如 items）

2. 标准方法优先

   • 五大标准方法覆盖 70%+ 场景，确保一致性7：

     方法	HTTP 映射	功能
     List	GET	分页查询资源集合
     Get	GET	获取单个资源
     Create	POST	创建资源
     Update	PUT/PATCH	全量/部分更新资源
     Delete	DELETE	删除资源

   • 自定义方法仅用于非标准操作（如 :undelete），通过 POST /resource:verb 格式映射

---

一、用户管理（10个）

1. GET /v1/users
   ➔ 分页查询用户列表（参数：?page=2&limit=50）
2. POST /v1/users
   ➔ 创建新用户（Body包含用户JSON）
3. GET /v1/users/{userId}
   ➔ 获取指定ID的用户详情
4. PUT /v1/users/{userId}
   ➔ 全量更新用户信息
5. PATCH /v1/users/{userId}
   ➔ 部分更新用户（如仅修改邮箱）
6. DELETE /v1/users/{userId}
   ➔ 删除用户
7. GET /v1/users/{userId}/permissions
   ➔ 获取用户的权限列表（父子资源）
8. POST /v1/users/{userId}/avatar
   ➔ 为用户上传头像（子资源）
9. DELETE /v1/users/{userId}/sessions
   ➔ 终止用户所有活跃会话
10. GET /v1/users/{userId}/roles/{roleId}
    ➔ 查询用户绑定的特定角色详情

---

二、产品目录（15个）

11. GET /v1/products
    ➔ 过滤产品（?category=electronics&price<=1000）
12. POST /v1/products
    ➔ 创建新产品
13. GET /v1/products/{productId}
    ➔ 查询产品详情
14. PUT /v1/products/{productId}
    ➔ 全量更新产品信息
15. PATCH /v1/products/{productId}/stock
    ➔ 更新产品库存（部分更新）
16. DELETE /v1/products/{productId}
    ➔ 下架产品
17. GET /v1/products/{productId}/reviews
    ➔ 获取产品评价列表（父子）
18. POST /v1/products/{productId}/reviews
    ➔ 为产品添加评价
19. DELETE /v1/products/{productId}/reviews/{reviewId}
    ➔ 删除指定评价
20. GET /v1/products/{productId}/versions
    ➔ 查询产品历史版本（子资源）
21. POST /v1/products/{productId}/attachments
    ➔ 上传产品附件（如说明书）
22. GET /v1/categories/{categoryId}/products
    ➔ 按分类查询产品（父子）
23. PATCH /v1/products/{productId}/pricing
    ➔ 仅更新产品价格
24. POST /v1/products/batch-delete
    ➔ 批量删除产品（Body含ID列表）
25. GET /v1/brands/{brandId}/products
    ➔ 按品牌查询产品

---

三、订单系统（20个）

26. POST /v1/users/{userId}/orders
    ➔ 为用户创建订单（父子）
27. GET /v1/users/{userId}/orders/{orderId}
    ➔ 查询用户特定订单
28. DELETE /v1/users/{userId}/orders/{orderId}
    ➔ 取消订单
29. GET /v1/orders?status=shipped
    ➔ 全局过滤订单（独立资源）
30. PATCH /v1/orders/{orderId}/status
    ➔ 更新订单状态（如shipped）
31. POST /v1/orders/{orderId}/items
    ➔ 向订单中添加商品项
32. DELETE /v1/orders/{orderId}/items/{itemId}
    ➔ 从订单移除商品项
33. GET /v1/orders/{orderId}/invoice
    ➔ 下载订单发票
34. POST /v1/orders/{orderId}/refunds
    ➔ 发起退款请求
35. PUT /v1/orders/{orderId}/shipping-address
    ➔ 更新配送地址
36. GET /v1/users/{userId}/orders/history
    ➔ 查询用户历史订单
37. POST /v1/orders/batch-create
    ➔ 批量创建订单（企业场景）
38. PATCH /v1/orders/{orderId}/priority
    ➔ 调整订单优先级
39. GET /v1/warehouses/{warehouseId}/orders
    ➔ 查询仓库关联订单
40. POST /v1/orders/{orderId}/notifications
    ➔ 发送订单通知（如短信）
41. DELETE /v1/orders/{orderId}/attachments/{fileId}
    ➔ 删除订单附件
42. GET /v1/orders/{orderId}/timeline
    ➔ 获取订单状态时间线
43. PUT /v1/orders/{orderId}/coupon
    ➔ 应用优惠券到订单
44. POST /v1/orders/{orderId}/split
    ➔ 拆分订单（如分仓库发货）
45. GET /v1/orders/stats?period=monthly
    ➔ 获取订单统计报表

---

四、博客系统（15个）

46. POST /v1/blogs
    ➔ 创建博客文章
47. GET /v1/blogs/{blogId}/comments
    ➔ 获取文章评论（父子）
48. POST /v1/blogs/{blogId}/comments
    ➔ 新增评论
49. DELETE /v1/blogs/{blogId}/comments/{commentId}
    ➔ 删除评论
50. PATCH /v1/blogs/{blogId}/likes
    ➔ 更新文章点赞数
51. GET /v1/users/{userId}/blogs
    ➔ 查询用户所有文章
52. PUT /v1/blogs/{blogId}/content
    ➔ 全量更新文章内容
53. POST /v1/blogs/{blogId}/tags
    ➔ 为文章添加标签
54. DELETE /v1/blogs/{blogId}/tags/{tagId}
    ➔ 移除文章标签
55. GET /v1/tags/{tagName}/blogs
    ➔ 按标签查询文章
56. POST /v1/blogs/{blogId}/publish
    ➔ 发布草稿（特殊动作）
57. GET /v1/blogs/{blogId}/versions/{versionId}
    ➔ 获取文章历史版本
58. POST /v1/blogs/{blogId}/attachments
    ➔ 上传文章附件（如图片）
59. DELETE /v1/blogs/{blogId}/subscriptions
    ➔ 取消文章订阅
60. GET /v1/blogs/trending?top=10
    ➔ 获取热门文章排行

---

五、文件存储（15个）

61. POST /v1/files
    ➔ 上传文件（返回文件ID）
62. GET /v1/files/{fileId}
    ➔ 下载文件
63. DELETE /v1/files/{fileId}
    ➔ 删除文件
64. GET /v1/folders/{folderId}/files
    ➔ 列出文件夹内文件（父子）
65. POST /v1/folders/{folderId}/files
    ➔ 向文件夹上传文件
66. PATCH /v1/files/{fileId}/permissions
    ➔ 修改文件权限（部分更新）
67. PUT /v1/files/{fileId}/metadata
    ➔ 更新文件元数据（如作者）
68. GET /v1/files/{fileId}/history
    ➔ 获取文件版本历史
69. POST /v1/files/{fileId}/restore?version=2
    ➔ 恢复文件到指定版本
70. DELETE /v1/folders/{folderId}
    ➔ 删除文件夹（递归删除子项）
71. PATCH /v1/shared-links/{linkId}
    ➔ 更新文件分享链接设置
72. GET /v1/users/{userId}/trash/files
    ➔ 查询用户回收站文件
73. POST /v1/files/{fileId}/move
    ➔ 移动文件到新路径
74. GET /v1/files/search?name=report.docx
    ➔ 全局文件搜索
75. POST /v1/files/zip
    ➔ 批量打包下载文件（Body含ID列表）

---

六、组织架构（25个）

76. POST /v1/companies
    ➔ 创建公司
77. GET /v1/companies/{companyId}/departments
    ➔ 查询公司部门列表（父子）4
78. POST /v1/companies/{companyId}/departments
    ➔ 新增部门
79. GET /v1/departments/{deptId}/employees
    ➔ 获取部门员工
80. POST /v1/departments/{deptId}/employees
    ➔ 向部门添加员工
81. DELETE /v1/departments/{deptId}/employees/{empId}
    ➔ 从部门移除员工
82. PUT /v1/employees/{empId}/manager
    ➔ 更新员工直属经理
83. GET /v1/companies/{companyId}/projects
    ➔ 查询公司项目
84. POST /v1/projects/{projectId}/teams
    ➔ 为项目分配团队
85. DELETE /v1/companies/{companyId}/departments/{deptId}
    ➔ 删除部门（需处理员工转移）
86. PATCH /v1/employees/{empId}/status
    ➔ 更新员工状态（如在职/离职）
87. GET /v1/teams/{teamId}/members
    ➔ 获取团队成员
88. POST /v1/teams/{teamId}/tasks
    ➔ 为团队创建任务
89. GET /v1/employees/{empId}/reports
    ➔ 获取员工下属（汇报线）
90. PUT /v1/projects/{projectId}/budget
    ➔ 更新项目预算
91. POST /v1/companies/{companyId}/locations
    ➔ 添加办公地点
92. DELETE /v1/companies/{companyId}/locations/{locId}
    ➔ 移除办公地点
93. GET /v1/employees/{empId}/attendance?month=2025-03
    ➔ 查询员工考勤记录
94. POST /v1/employees/batch-update
    ➔ 批量更新员工信息（如调薪）
95. PATCH /v1/tasks/{taskId}/progress
    ➔ 更新任务进度百分比
96. GET /v1/companies/{companyId}/analytics/salaries
    ➔ 获取公司薪资分析报表
97. POST /v1/teams/{teamId}/meetings
    ➔ 安排团队会议
98. DELETE /v1/tasks/{taskId}/assignments/{empId}
    ➔ 解除员工的任务分配
99. PUT /v1/companies/{companyId}/policies/{policyId}
    ➔ 更新公司政策文档
100. GET /v1/companies/{companyId}/hierarchy
     ➔ 获取组织架构树（嵌套父子结构）

---

设计要点总结

1. 父子资源嵌套原则：

   • 子资源URI必须包含父ID（如/users/{userId}/orders）
   • 若子资源可独立存在，需提供独立入口（如/orders/{orderId}）

2. HTTP方法选择：

   • PATCH用于局部更新，PUT用于全量替换
   • 非CRUD操作转为资源（如POST /files/{id}/restore）

3. 批量操作：

   • 使用POST + 资源复数形式（如POST /users/batch-delete）

4. 错误处理：

   • 返回标准HTTP状态码（如404 Not Found）及错误JSON

5. 扩展性：

   • 通过fields参数过滤响应字段（?fields=id,name）

自定义方法

自定义方法应谨慎使用，优先考虑标准方法，仅在标准语义无法满足时采用此模式。

根据 Google API 设计指南，当操作无法映射到标准 CRUD（Create、Read、Update、Delete）方法时，应使用自定义方法 （Custom Methods）。这些方法通过 POST 请求实现，并在资源 URI 后附加 :{action} 表示非标准操作。

在Google API设计规范中，自定义方法使用 :{action} 而非 /{action} 的URI格式（如 :batchDelete 而非 /batchDelete），这是经过严谨设计的语法规则，核心原因如下：

---

设计原则：区分资源 vs 操作

1. /{action} 的歧义性

   若使用 /batchDelete 格式，会被解析为子资源路径 （如存在名为 batchDelete 的资源），而非操作指令。
   错误示例：

   POST /v1/users/batchDelete

   • 语义歧义：系统可能误认为要操作 users 下的 batchDelete 资源。

2. :{action} 的明确性

   冒号语法显式声明这是一个动作 （动词），而非资源（名词）。
   正确示例：

   POST /v1/users:batchDelete

   • 语义清晰：对 users 资源执行 batchDelete 操作。

---

二、语法规范：避免与子资源冲突

场景	路径格式	含义
子资源	/users/{userId}/photos	查询用户相册（资源实体）
自定义方法	/users:search	执行搜索（操作指令）

若使用 /users/search：

• 系统会误认为 search 是 users 的子资源（如返回所有"search"类型的用户）。
• 而 :search 明确表示动作（在用户集合上执行搜索）。

---

特殊案例：为什么 /search 被允许？

Google规范中 /search 是唯一例外 ，因其被定义为标准方法而非自定义方法：

GET /v1/users/search?query=john

• 原因 ：search 本质是 List 方法的扩展（过滤资源），属于标准查询行为。

• 规范依据：

  当操作是对资源的"查询"时（如过滤、排序），使用独立端点 /search。

---

四、关键结论：何时用 : vs /

操作类型	示例	URI 格式
自定义方法（非标准操作）	批量删除、发布、恢复	POST /res:action
标准查询（过滤/搜索）	搜索、复合条件列表	GET /res/search
子资源操作	获取用户的订单	GET /users/{id}/orders

以下是符合规范的 20 个典型示例，覆盖不同业务场景：

⚙️ 一、计算与处理类操作

1. batchDelete

   • 场景：批量删除资源（如订单、文件）
   • URI ：POST /v1/orders:batchDelete

2. calculate

   • 场景：执行复杂计算（如税费、预算）
   • URI ：POST /v1/invoices/{id}:calculateTax

3. generateReport

   • 场景：生成动态报表（如销售统计）
   • URI ：POST /v1/sales:generateReport

4. restore

   • 场景：恢复已删除资源（如文件、用户）
   • URI ：POST /v1/files/{fileId}:restore

5. translate

   • 场景：翻译文本内容
   • URI ：POST /v1/documents/{id}:translate

🔄 二、状态与流程管理

6. publish

   • 场景：发布草稿资源（如博客、标签）
   • URI ：POST /v1/blogs/{blogId}:publish

7. approve

   • 场景：审批工作流任务
   • URI ：POST /v1/tasks/{taskId}:approve

8. cancel

   • 场景：取消进行中操作（如订单、订阅）
   • URI ：POST /v1/orders/{orderId}:cancel

9. disable

   • 场景：停用资源（如账号、服务）
   • URI ：POST /v1/users/{userId}:disable

10. resetPassword

    • 场景：重置用户密码（非标准更新）
    • URI ：POST /v1/users/{userId}:resetPassword

📦 三、批量与聚合操作

11. import

    • 场景：批量导入数据（如用户列表）
    • URI ：POST /v1/users:import

12. export

    • 场景：导出资源集合（如报告数据）
    • URI ：POST /v1/reports:export

13. sync

    • 场景：多端数据同步（如日历事件）
    • URI ：POST /v1/calendars/{id}:sync

♻️ 四、资源生命周期扩展

14. undelete

    • 场景：恢复逻辑删除的资源
    • URI ：POST /v1/projects/{projectId}:undelete

15. archive

    • 场景：归档不再活跃的资源
    • URI ：POST /v1/documents/{id}:archive

16. validate

    • 场景：校验资源有效性（如配置、表单）
    • URI ：POST /v1/forms/{formId}:validate

🔗 五、关联资源操作

17. attach

    • 场景：关联独立资源（如标签附加到文件）
    • URI ：POST /v1/files/{fileId}/labels:attach

18. clone

    • 场景：复制资源（如项目模板）
    • URI ：POST /v1/templates/{id}:clone

19. move

    • 场景：移动资源位置（如文件目录）
    • URI ：POST /v1/files/{fileId}:move

20. merge

    • 场景：合并多个资源（如联系人去重）
    • URI ：POST /v1/contacts:merge

以上示例完全遵循Google API设计规范，强调URI可读性、HTTP方法语义化及资源分层管理。完整规范可参考：Google Cloud API Design Guide。