在这个微服务的世界里，后端API的一致设计是必不可少的。今天，我们将讨论一些要遵循的最佳实践。我们将保持简短和甜蜜-所以系好安全带，让我们开始吧！首先是一些术语任何API设计都遵循一个叫做“面向资源的设计”的原则：Resource：资源是数据的一部分，eg：UsersCollection：一组资源称为集合，eg：UserListURL：标识一个资源或收集位置，例如：/user1。对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属性使用驼峰式命名如果你正在构建一个请求主体或响应主体是JSON的系统，那么属性名称应该使用驼峰式命名。不应该：{user_name:"MohammadFaisal"user_id:"1"}应该：{userName:"MohammadFaisal"userId:"1"}8.监控RESTfulHTTP服务必须实现/health和/version和/metricsAPI端点.他们将提供以下信息。/health使用200OK状态代码响应对/health的请求。/version响应带有版本号的/version请求。/metrics端点将提供各种指标，例如平均响应时间。还强烈建议使用/debug和/status端点。9.不要使用table_name作为资源名称不要只使用表名作为资源名称。从长远来看，这种懒惰是有害的。不应该：product_order应该：product-orders这是因为暴露底层架构不是你的目的。10、使用API??设计工具编写好的文档有很多好的API设计工具，例如：API消费者的用户体验。11.对版本使用简单的序号始终对API使用版本控制并将它们移到左侧，以便它们具有最大的范围。版本号应为v1、v2等。应该：http://api.domain.com/v1/shop...始终在您的API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。12.在响应正文中包含资源总数如果API返回对象列表，请始终在响应中包含资源总数。您可以为此使用total属性。Shouldn't:{users:[...]}Should:{users:[...],total:34}13.接受limit和offset参数在GET操作中总是接受limit和offset参数。应该：GET/shops?offset=5&limit=5这是因为前端分页需要。14、get字段查询参数返回的数据量也要考虑在内。添加fields参数以仅公开API中需要的字段。示例：仅返回商店的名称、地址和联系信息。GET/shops?fields=id,name,address,contact在某些情况下它还有助于减少响应大小。15.不要在URL中传递authtoken这是一个非常糟糕的做法，因为url经常被记录并且authtoken被不必要地记录。不应该是：GET/shops/123?token=some_kind_of_authenticaiton_token相反，通过标头传递它们：Authorization:Bearerxxxxxx,Extrayyyyy此外，授权令牌应该是短暂的。16.验证内容类型服务器不应该假定内容类型。例如，如果您接受application/x-www-form-urlencoded，那么攻击者可以创建一个表单并触发一个简单的POST请求。因此，始终验证内容类型，如果要使用默认内容类型，请使用：content-type:application/json17。将HTTP方法用于CRUD函数HTTP方法用于解释CRUD函数。GET：检索资源的表示。POST：创建新的资源和子资源。PUT：更新现有资源。PATCH：更新现有资源，它只更新提供的字段而不更新其他字段。DELETE：删除现有资源。18.在嵌套资源的URL中使用关系以下是一些实际示例：GET/shops/2/products：获取商店2中所有产品的列表。GET/shops/2/products/31：获取产品31的详细信息，属于商店2。DELETE/shops/2/products/31：应删除属于商店2的产品31。PUT/shops/2/products/31：应更新产品31的信息，仅在资源上使用PUT-URL，不是集合。POST/shops：应该创建一个新商店并返回创建的新商店的详细信息。在集合url上使用POST。19.CORS（跨源资源共享）必须支持所有面向公众的API的CORS（跨源资源共享）标头。考虑支持CORS允许的“*”来源并通过有效的OAuth令牌强制执行授权。避免将用户凭据与原始身份验证相结合。20.安全在所有端点、资源和服务上实施HTTPS（tls加密）。强制并要求所有回调url、推送通知端点和webhook都使用HTTPS。21.错误当客户端向服务发出无效或不正确的请求，或者向服务传递无效或不正确的数据，而服务拒绝请求时，就会发生错误，或者更具体地说是服务错误。示例包括无效的身份验证凭据、不正确的参数、未知的版本ID等。当客户端请求由于一个或多个服务错误而被拒绝时，必须返回4xxHTTP错误代码。考虑处理所有属性并在单个响应中返回多个验证问题。22.黄金法则如果您对您的API格式决定有疑问，这些黄金法则可以帮助我们做出正确的决定。扁平比嵌套好。简单胜于复杂。字符串比数字好。一致性优于定制。就是这样-如果你已经走到这一步，恭喜你！希望你学到了一些东西。来源：dockone.io/article/2434604链接：betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9译者：刘志超，软件工程师，DevOpsDays和HDZShenzhen的核心组织者目前就职于华为，从事云计算，专注于K8s和微服务。近期热点文章推荐：1.1000+Java面试题及答案（2022最新版）2.厉害了！Java协程来了。..3.SpringBoot2.x教程，太全面了！4.不要用爆破爆满画面，试试装饰者模式，这才是优雅的方式！！5.《Java开发手册（嵩山版）》最新发布，赶快下载吧！感觉不错，别忘了点赞+转发！
