【.com速译】本文将从SDK和文档的使用、向下兼容的维护、升级的处理、有效的测试五个方面与你探讨各种RESTAPI设计实践。不用说，API已经成为当今不同系统之间交换信息的事实标准。它通常有助于更好地集成系统中的各种组件。那么我们如何才能设计出更好的API呢？在本文中，我将与您讨论在设计和实现各种RESTAPI时值得遵循的良好实践原则。1.不用自己写代码，用好各种客户端SDK。如果服务提供商或创建者给出了一套开发工具包（SDK），那么我们应该在API调用中使用它们，而不是编写代码，在这个机器REST调用之上，去重写自己的客户端库。一个典型的例子是用于与AmazonWebServices交互的AWSSDK。选择使用AWSSDK不仅有助于减缓团队的学习曲线并快速上手，还可以节省编写与安全、网络超时、重试和回滚相关的逻辑事务的时间。此外，由于这些SDK由提供商维护，开发人员无需繁琐的测试、修复和更改即可支持各种新的API节点。如今，大多数SDK不仅是开源的，而且支持并快速集成包括REST、WebSocket、gRPC在内的各种标准协议。APISDK的主要缺点是：可用性，以及它对您选择的编程语言的支持程度。对于这种情况，开发人员有时需要开发自定义REST客户端。我的经验是，开发人员应该将其设计和实施为一个单独的Maven项目，托管在企业Git存储库中，完整记录，并由组织中的所有内部团队共享。2.熟练使用文档上面提到的支持文档不仅是API开发者，尤其是没有任何开发背景的开发者开始开发的基本要素，而且文档往往是大多数现代开发框架的一部分。组成部分。作为开发者，我经常可以根据已有的文档轻松进行API相关的测试，而不必临时去浩瀚的社区或论坛上搜索相关资料。通常，API的相关文档可以向用户介绍API的基本功能、各种参数以及预期的负载（payload）模型。当然，我在参与各种项目中也发现，虽然有些文档内容很详细（包括负载模型的例子），但有些文档已经落后于当前版本的API。因此，我经常在项目中使用Swagger，将文件方法、参数、模型紧密集成到服务器端代码中，使客户端和文件系统服务器同步更新同步。3.遵循标准的端点方法在设计API时，很多开发者不仅容易忽略端点的标准命名约定，也不按照HTTP的各种动词定义来操作。网上的资料很多，只要你肯花时间搜索，一定能搜到很多。下面分享几个我一直严格遵守的方法，也请部门开发人员继续遵守：不要在端点中混用大小写字母。例如：请将“/users/userId”更改为“/users/{id}”。请将POST"/deleteUser/userId"替换为DELETE"users/{id}"。始终在URL中使用版本控制，例如：我会将“/api/v1/”作为URL的必需部分。使“https”成为客户端连接的默认选项。请加载验证组件作为代码处理的第一步。它不能留给后处理，甚至不能留给异常捕获器处理。4.处置升级我遇到过这样一个案例：我们的一个服务一直在使用某个API传递一些数据，但是有一天它突然停止工作了。经过多轮电子邮件和电话会议的讨论和研究，我们最终发现这是因为API的负载发生了变化——添加了一个必填字段。但是，我们在这个API的升级过程中并没有考虑到向后兼容性！为了避免此类错误，我们应该使用现有的CI（持续集成）流程尽早发现它们。作为API开发人员，在更改目标API时应充分考虑现有客户。例如：在请求的文本中，那些新字段是否应该使用默认值？还是应该定义一个新的版本端点，例如“/api/v2”？5.测试这里所说的测试，不仅仅是功能测试，还包括负载测试。您应该能够看到目标服务器通常每分钟可以处理多少API调用，以及当网络延迟增加时响应时间如何变化。如今，越来越多的企业会在全球部署不同规模的数据中心，或者采用多区域的云环境。例如：我们需要知道您托管在美国西部的API服务器是否能够为那些来自美国东部、欧洲、澳大利亚甚至亚洲的客户端实例请求提供足够的带宽和连接数.就我个人的经验而言，我更喜欢使用API测试工具，例如：Postman或ApacheJMeter，而不是从头开始编写工具和用例。它们不仅节省了我的时间，还让我可以轻松地签入git并导出各种模板。总结以上五点经验是我个人在实际项目中设计RESTAPI的总结。希望它们能给你的API开发，以及软件工程的其他方面带来一些启发，让你少走一些弯路。【原标题】更好的RESTAPI设计的5个技巧作者：PreetdeepKumar
