微服务时代 API 设计的 22 种最佳实践

对糟糕的 API 感到沮丧？

在微服务领域，后端 API 的一致设计至关重要。

今天我们将讨论一些需要遵循的最佳实践。我们会保持简短和甜蜜 - 所以插入它并开始吧！

先介绍一些术语

任何API设计都遵循“面向资源的设计”原则：

• 资源：资源就是一段数据，例如：用户
• 集合：一组资源它称为集合，例如：用户列表
• URL：标识资源或集合的位置，例如：/user

1。使用 kebab 大小写（连字符分隔形式）作为 URL

，例如，如果您想要获取订单列表。

不：

/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 属性使用驼峰命名法

如果您正在构建请求正文或响应正文为 JSON 的系统，则属性名称必须使用驼峰命名法。

性别：

{
用户名：“Mohammad Faisal”
用户 ID：“1”
}
}
} } 用户名：“Mohammad Faisal " "
userId: "1"
}

8. 监控

RESTful HTTP 服务必须实现 /health 和 /version 以及 /metricsAPI 端点。他们提供以下信息。

/health

使用状态代码 200 OK 响应 /health 请求。

/version

使用版本号响应 /version 请求。

/指标

此端点提供各种指标，例如平均响应时间。

还强烈建议使用 /debug 和 /status 端点。

9。不要使用 table_name 作为资源名称

不要仅使用 table_name 作为资源名称。从长远来看，这种懒惰是有害的。

否：

product_order

：

product-orders

这是因为它并不是为了揭示底层架构。

10。使用 API 设计工具

有很多好的 API 设计工具可以用来编写好的文档，例如：

• API 蓝图：https://apiblueprint.org/
• Swagger：https:///swagger.io/

良好且详细的文档可以为API使用者提供良好的用户体验。

11。对版本使用简单的序列号

始终对 API 使用版本号，并将其向左移动以获得最大范围。版本号为 v1、v2 等。一定是有价值的。如果 API 由外部实体使用，则

必须。

12。在响应正文中指定资源总数

如果 API 返回对象列表，则响应始终包含资源总数。为此，您可以使用total 属性。

否：

{
用户：[
...
]
}
}
}

GET /getusers

用户：[
.. .
]，
总计：34
}

13。接受限制和偏移参数

在 GET 操作中始终接受限制和偏移参数。

应该是：

GET /shops?offset=5&limit=5

这是因为首页分页需要它。

14。检索字段查询参数

还必须考虑返回的数据量。添加字段参数以仅显示 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。使用 HTTP 方法实现 CRUD 功能

HTTP 方法用于解释 CRUD 功能。

GET：获取资源的表示形式。

POST：创建新资源和子资源。

PUT：更新现有资源。

PATCH：更新现有资源，仅更新指定字段，不更新其他字段。

DELETE：删除现有资源。

18。使用嵌入资源 URL 中的链接

以下是一些实际示例：

• GET /shops/2/products：获取商店 2 中所有产品的列表。
• GET /shops/2/products/31：获取产品 31 的详细信息。产品 31 属于商店 2。
• DELETE /stores/2/products/31：必须删除产品 31，它属于商店 2。
• PUT /shops/2/products/31：需要更新产品 31 信息，仅在资源 URL 上使用 PUT，而不是在集合上使用 PUT。
• POST /shops：创建一个新商店并返回创建的新商店的详细信息。对集合 URL 使用 POST。

19。 CORS（跨源资源共享）

确保所有公共 API 支持 CORS（跨源资源共享）标头。

考虑支持启用 CORS 的“*”源并使用有效的 OAuth 令牌强制授权。

避免将用户凭据与原始身份验证相结合。

20。安全性

在所有端点、资源和服务上实施 HTTPS（tls 加密）。

强制并要求所有回调 URL、推送通知端点和 Webhook 使用 HTTPS。

21。错误

当客户端向服务发出无效或不正确的请求，或者向服务提供无效或不正确的数据，而服务拒绝请求时，或者更准确地说，发生服务错误时，就会发生错误。

示例：无效凭证、错误参数、未知版本 ID 等。

• 如果客户端请求由于一个或多个服务错误而被拒绝，请务必返回 4xx HTTP 错误代码。
• 考虑处理所有属性并在单个响应中返回多个验证问题。

22。黄金法则

如果您对 API 格式决策有疑问，这些黄金法则可以帮助您做出正确的决定。

• 平放比嵌入更好。
• 简单胜于复杂。
• 字符串比数字更好。
• 一致性比定制更好。

就是这样 - 如果您已经完成了这一步，那么恭喜您！我希望你学到了一些东西。