【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}/subscripqions
    ? 取消文章订阅

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}/locetions
    ? 添加办公地点

92. DELETE /v1/companies/{companyId}/locetions/{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 的资源），而非操作指令。
   错误示例：

   bash体验AI代码助手代码解读复制代码POST /v1/users/batchDelete

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

2. :{action} 的明确性
   冒号语法显式声明这是一个动作（动词），而非资源（名词）。
   正确示例：

   bash体验AI代码助手代码解读复制代码POST /v1/users:batchDelete

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

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

若使用 /users/search：

• 系统会误认为 search 是 users 的子资源（如返回所有"search"类型的用户）。

• 而 :search 明确表示动作（在用户集合上执行搜索）。

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

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

bash体验AI代码助手代码解读复制代码GET /v1/users/search?query=john

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

• 规范依据：

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

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

以下是符合规范的 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方法语义化及资源分层管理。完整规范可参考：