共计 3354 个字符,预计需要花费 9 分钟才能阅读完成。
在这个微服务的世界里,后端 API 的一致性设计是必不可少的。
明天,咱们将探讨一些可遵循的最佳实际。咱们将放弃简短和苦涩——所以系好安全带,登程咯!
首先介绍一些术语
任何 API 设计都遵循一种叫做“面向资源设计”的准则:
- 资源 :资源是数据的一部分,例如:用户
- 汇合 :一组资源称为汇合,例如:用户列表
- URL:标识资源或汇合的地位,例如:/user
1. 对 URL 应用 kebab-case(短横线小写隔开模式)
例如,如果你想要取得订单列表。
不应该:
/systemOrders 或 /system_orders
应该:
/system-orders
2. 参数应用 camelCase(驼峰模式)
例如,如果你想从一个特定的商店购买产品。
不应该:
/system-orders/{order_id}
或者:
/system-orders/{OrderId}
应该:
/system-orders/{orderId}
3. 指向汇合的复数名称
如果你想取得零碎的所有用户。
不应该:
GET /user
或:
GET /User
应该:
GET /users
4. URL 以汇合开始,以标识符完结
如果要放弃概念的单一性和一致性。
不应该:
GET /shops/:shopId/category/:categoryId/price
这很蹩脚,因为它指向的是一个属性而不是资源。
应该:
GET /shops/:shopId/ 或 GET /category/:categoryId
5. 让动词远离你的资源 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/json
17. 对 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 开发手册(嵩山版)》最新公布,速速下载!
感觉不错,别忘了顺手点赞 + 转发哦!