弄懂“资源”与“集合”：RESTful API 设计核心指南

本文用一张图 + 3 段代码，带你分清“资源”与“集合”，掌握 URI 命名、最小数据、分页封装等 7 条最佳实践；文末 5 颗 AI 提示词彩蛋，让“代码、文档、KPI”一键自动化。🚀

一、什么是资源（Resource）？

资源是可通过唯一 URI 访问的具体数据或对象——用户、订单、发票、博客文章都是资源。
示例：一张发票

GET /invoices/645E79D9E14

{
  "id": "645E79D9E14",
  "invoiceNumber": "INV-2024-001",
  "customer": "Acme Corporation",
  "amountDue": 500.00,
  "links": {
    "self": "/invoices/645E79D9E14",
    "customer": "/customers/Acme Corporation",
    "payment": "/invoices/645E79D9E14/payments"
  }
}

• links 让客户端无需拼接 URI，即可跳转关联资源
• 字段即状态，URI 即标识——这就是 REST 的核心

二、什么是集合（Collection）？

集合是同一类型资源的列表，本身也是资源，通常用数组表示：

GET /invoices

[
  {
    "id": "645E79D9E14",
    "invoiceNumber": "INV-2024-001",
    "customer": "Acme Corporation",
    "amountDue": 500.00,
    "dueDate": "2024-08-15"
  },
  {
    "id": "646D15F77838",
    "invoiceNumber": "INV-2024-002",
    "customer": "Monsters Ltd.",
    "amountDue": 750.00,
    "dueDate": "2024-08-20"
  }
]

• 只返回“摘要”字段 → 减少带宽
• 提供 self 或 link → 想再看详情再请求

三、与资源和集合交互的 HTTP 动词

用状态码明确结果：201 Created、204 No Content、404 Not Found

四、设计最佳实践（7 条速成）

1. URI 用名词复数
   ✅ /posts ❌ /getPosts
   HTTP 动词已表达动作，URI 只需说明“对象”

2. 集合返回最小数据
   只给“列表够用”的字段，详情再调单条资源，避免响应膨胀

3. 提供链接，减少客户端拼装

   { "id": 123, "title": "Hello", "link": "/posts/123" }

   GitHub、Twitter、Stripe 均如此，真正落地 HATEOAS

4. 分页 & 封装
   Stripe 风格：

   {
    "object": "list",
    "url": "/v1/charges",
    "has_more": true,
    "data": [ {...}, {...} ]
   }

   客户端只需判断 has_more 继续翻页

5. 不要暴露数据库主键或表结构
   内部 user_id 改名 public_id，表拆分/合并不影响 API

6. 版本号放 URL 或 Header
   /v1/invoices → /v2/invoices，旧版给 deprecation 日期

7. 一致的错误格式

   {
    "error": {
      "code": "INV_NOT_FOUND",
      "message": "Invoice not found",
      "target": "invoice_id"
    }
   }

五、真实世界对照：GitHub / Twitter / Stripe

• GitHub — 每仓库都有 url 字段，客户端无需拼地址
• Twitter — 时间线即集合，自带 url 指向单条推文
• Stripe — 集合统一封装在 data[]，附 has_more 分页信号

六、常见陷阱速查表

七、AI 提示词彩蛋：把最佳实践自动化

八、总结口诀

• 资源 = 数据 + 状态 + 链接
• 集合 = 数组 + 摘要 + 分页
• URI 永远复数名词，HTTP 动词表动作
• 模型 ≠ 数据库表，对外聚合、对内灵活
• 给链接、给分页、给错误码，客户端才能零拼接

把口诀落到代码，再加上 AI 提示词帮你自动检查——你的 API 就已经领先 80% 的同行。🎯

原文链接: https://apisyouwonthate.com/blog/understanding-resources-and-collections-in-restful-apis/