共计 3354 个字符，预计需要花费 9 分钟才能阅读完成。
在这个微服务的世界里，后端 API 的一致性设计是必不可少的。
明天，咱们将探讨一些可遵循的最佳实际。咱们将放弃简短和苦涩——所以系好安全带，登程咯！
首先介绍一些术语
任何 API 设计都遵循一种叫做“面向资源设计”的准则：
- 资源 ：资源是数据的一部分，例如：用户
- 汇合 ：一组资源称为汇合，例如：用户列表
- URL：标识资源或汇合的地位，例如：/user
1. 对 URL 应用 kebab-case（短横线小写隔开模式）
例如，如果你想要取得订单列表。
不应该：
/systemOrders 或 /system_orders应该：
/system-orders2. 参数应用 camelCase（驼峰模式）
例如，如果你想从一个特定的商店购买产品。
不应该：
/system-orders/{order_id}或者：
/system-orders/{OrderId}应该：
/system-orders/{orderId}3. 指向汇合的复数名称
如果你想取得零碎的所有用户。
不应该：
GET /user或：
GET /User应该：
GET /users4. URL 以汇合开始，以标识符完结
如果要放弃概念的单一性和一致性。
不应该：
GET /shops/:shopId/category/:categoryId/price这很蹩脚，因为它指向的是一个属性而不是资源。
应该：
GET /shops/:shopId/ 或 GET /category/:categoryId5. 让动词远离你的资源 URL
不要在 URL 中应用动词来表白你的用意。相同，应用适当的 HTTP 办法来形容操作。
不应该：
POST /updateuser/{userId}或：
GET /getusers应该：
PUT /user/{userId}6. 对非资源 URL 应用动词
如果你有一个端点，它只返回一个操作。在这种状况下，你能够应用动词。例如，如果你想要向用户从新发送警报。
应该：
POST /alarm/245743/resend请记住，这些不是咱们的 CRUD 操作。相同，它们被认为是在咱们的零碎中执行特定工作的函数。
7. JSON 属性应用 camelCase 驼峰模式
如果你正在构建一个申请体或响应体为 JSON 的零碎，那么属性名应该应用驼峰大小写。
不应该：
{
user_name: "Mohammad Faisal"
user_id: "1"
}应该：
{
userName: "Mohammad Faisal"
userId: "1"
}8. 监控
RESTful HTTP 服务必须实现 /health 和 /version 和 /metricsAPI 端点。他们将提供以下信息。
/health
用 200 OK 状态码响应对 /health 的申请。
/version
用版本号响应对 /version 的申请。
/metrics
这个端点将提供各种指标，如均匀响应工夫。
也强烈推荐应用 /debug 和 /status 端点。
9. 不要应用 table_name 作为资源名
不要只应用表名作为资源名。从久远来看，这种懈怠是无害的。
不应该：
product_order应该：
product-orders这是因为公开底层体系结构不是你的目标。
10. 应用 API 设计工具
有许多好的 API 设计工具用于编写好的文档，例如：
- API 蓝图 ：https://apiblueprint.org/
- Swagger：https://swagger.io/
领有良好而具体的文档能够为 API 使用者带来良好的用户体验。
11. 应用简略序数作为版本
始终对 API 应用版本控制，并将其向左挪动，使其具备最大的作用域。版本号应该是 v1，v2 等等。
应该：http://api.domain.com/v1/shop…
始终在 API 中应用版本控制，因为如果 API 被内部实体应用，更改端点可能会毁坏它们的性能。
12. 在你的响应体中包含总资源数
如果 API 返回一个对象列表，则响应中总是蕴含资源的总数。你能够为此应用 total 属性。
不应该：
{
users: [...]
}应该：
{
users: [...],
total: 34
}13. 承受 limit 和 offset 参数
在 GET 操作中始终承受 limit 和 offset 参数。
应该：
GET /shops?offset=5&limit=5这是因为它对于前端的分页是必要的。
14. 获取字段查问参数
返回的数据量也应该思考在内。增加一个 fields 参数，只公开 API 中必须的字段。
例子：
只返回商店的名称，地址和联系方式。
GET /shops?fields=id,name,address,contact在某些状况下，它还有助于缩小响应大小。
15. 不要在 URL 中通过认证令牌
这是一种十分蹩脚的做法，因为 url 常常被记录，而身份验证令牌也会被不必要地记录。
不应该：
GET /shops/123?token=some_kind_of_authenticaiton_token相同，通过头部传递它们：
Authorization: Bearer xxxxxx, Extra yyyyy此外，受权令牌应该是短暂有效期的。
16. 验证内容类型
服务器不应该假设内容类型。例如，如果你承受 application/x-www-form-urlencoded，那么攻击者能够创立一个表单并触发一个简略的 POST 申请。
因而，始终验证内容类型，如果你想应用默认的内容类型，请应用：
content-type: application/json17. 对 CRUD 函数应用 HTTP 办法
HTTP 办法用于解释 CRUD 性能。
GET：检索资源的示意模式。
POST：创立新的资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源，它只更新提供的字段，而不更新其余字段。
DELETE：删除已存在的资源。
18. 在嵌套资源的 URL 中应用关系
以下是一些理论例子：
- GET /shops/2/products：从 shop 2 获取所有产品的列表。
- GET /shops/2/products/31：获取产品 31 的详细信息，产品 31 属于 shop 2。
- DELETE /shops/2/products/31：应该删除产品 31，它属于商店 2。
- PUT /shops/2/products/31：应该更新产品 31 的信息，只在 resource-URL 上应用 PUT，而不是汇合。
- POST /shops：应该创立一个新的商店，并返回创立的新商店的详细信息。在汇合 url 上应用 POST。
19. CORS（跨源资源共享）
肯定要为所有面向公共的 API 反对 CORS（跨源资源共享）头部。
思考反对 CORS 容许的“*”起源，并通过无效的 OAuth 令牌强制受权。
防止将用户凭证与原始验证相结合。
20. 平安
在所有端点、资源和服务上施行 HTTPS（tls 加密）。
强制并要求所有回调 url、推送告诉端点和 webhooks 应用 HTTPS。
21. 谬误
当客户端向服务收回有效或不正确的申请，或向服务传递有效或不正确的数据，而服务回绝该申请时，就会呈现谬误，或者更具体地说，呈现服务谬误。
例子包含有效的身份验证凭证、不正确的参数、未知的版本 id 等。
- 当因为一个或多个服务谬误而回绝客户端申请时，肯定要返回 4xx HTTP 错误代码。
- 思考解决所有属性，而后在单个响应中返回多个验证问题。
22. 黄金法令
如果您对 API 格局的决定有疑难，这些黄金规定能够帮忙咱们做出正确的决定。
- 扁平比嵌套好。
- 简略胜于简单。
- 字符串比数字好。
- 一致性比定制更好。
就是这样——如果你曾经走到了这一步，祝贺你！心愿你学到了一些货色。
起源：dockone.io/article/2434604
链接：betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
译者：刘志超，软件工程师、DevOpsDays、HDZ 深圳外围组织者，目前供职于华为，从事云计算工作，专一于 K8s、微服务畛域。
近期热文举荐：
1.1,000+ 道 Java 面试题及答案整顿 (2022 最新版)
2. 劲爆！Java 协程要来了。。。
3.Spring Boot 2.x 教程，太全了！
4. 别再写满屏的爆爆爆炸类了，试试装璜器模式，这才是优雅的形式！！
5.《Java 开发手册（嵩山版）》最新公布，速速下载！
感觉不错，别忘了顺手点赞 + 转发哦！