如果您正在构建使用某种客户端/服务器模型的应用程序，则需要应用程序编程接口 (API)。API 是一个进程和另一个进程之间明确定义的边界。Web 应用程序中常见的边界是 REST/JSON API。
虽然开发人员可能主要关注使 API 工作（或发挥作用），但仍有一些“非功能性”需求需要他们关注。所有 API 的四个必备非功能性需求是：
- 安全性
- 文档
- 验证
- 测试
安全性
安全性是软件开发中的基本要求。API 开发人员需要关注以下四个安全领域：
- HTTPS/SSL 证书
- 跨域资源共享
- 身份验证和 JSON Web Tokens
- 授权和范围
1. HTTPS/SSL 证书
Web 的黄金标准是使用 SSL 证书的 HTTPS，并且 Let's Encrypt 可以帮助您实现这一目标。它是由非营利性互联网安全研究小组 (ISRG) 提供的免费、自动化和开放的证书颁发机构。
Let's Encrypt 的软件为您的域生成中央授权证书。这些证书确保从您的 API 到客户端的数据负载从端到端加密。
Let's Encrypt 支持多种证书管理部署选项；请查看其文档，找到适合您需求的解决方案。
2. 跨域资源共享
CORS 是一种特定于浏览器的安全策略预检。如果您的 API 服务器与请求客户端的域不在同一域中，则您需要处理 CORS。例如，如果您的服务器在 api.domain-a.com 上运行，并且收到来自 domain-b.com 的客户端请求，则 CORS 会发送 HTTP 预检请求，以查看您的 API 服务是否接受来自客户端域的客户端请求。
“跨域资源共享 (CORS) 是一种基于 HTTP 标头的机制，允许服务器指示浏览器应允许从哪些其他来源（域、方案或端口）加载资源，而不是其自身的来源。”
有许多用于 Node.js 的辅助库，可以帮助 API 开发人员处理 CORS。
3. 身份验证和 JSON Web Tokens
验证 API 中经过身份验证的用户有多种方法，但最好的方法之一是使用 JSON Web Tokens (JWT)。这些令牌使用各种类型的知名加密库进行签名。
当客户端登录时，身份管理服务会向客户端提供 JWT。然后，客户端可以使用此令牌向 API 发出请求。API 可以访问公钥或密钥，用于验证令牌。
有几个库可用于帮助验证令牌，包括 jsonwebtoken。有关 JWT 以及每种语言中支持它的库的更多信息，请查看 JWT.io。
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken(req)
jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
if (err) { next(err) }
req.session = decoded
next()
})
}4. 授权和范围
身份验证（或身份验证）很重要，但授权也很重要，即，经过验证的客户端是否具有执行此请求的权限？ 这就是 范围 的价值所在。当客户端通过身份管理服务器进行身份验证并创建 JWT 令牌时，让身份管理服务为给定的经过身份验证的客户端提供范围，可以使 API 服务确定是否可以执行此经过验证的客户端请求，而无需执行额外的、代价高昂的访问控制列表查找。
范围是一个文本块（通常以空格分隔），描述 API 端点的访问能力。通常，范围分为资源和操作。这种模式非常适合 REST/JSON API，因为它们在 RESOURCE:ACTION 格式中结构非常相似（例如，ARTICLE:WRITE 或 ARTICLE:READ，其中 ARTICLE 是资源，READ 和 WRITE 是操作）。
这允许 API 专注于功能，而不是角色或用户。身份访问管理服务可以将角色和用户与范围关联起来，然后在经过验证的 JWT 中向客户端提供范围。
总结
在构建和部署 API 时，安全性应始终是最重要的要求之一。虽然安全性是一个广泛的主题，但解决这四个领域将使您的 API 在生产环境中处于有利地位。
文档
有什么比没有文档更糟糕的？过时的文档。
开发人员对文档有着爱恨交加的关系。尽管如此，文档仍然是 API 成功定义的重要组成部分。开发人员需要知道如何使用 API，而您创建的文档在教育开发人员如何最好地使用 API 方面起着巨大的作用。
API 文档需要关注以下三个领域：
- 开发者入门（README）
- 技术参考（规范）
- 用法（入门指南和其他指南）
1. 开发者入门
在构建 API 服务时，您需要指定诸如以下内容：API 的作用是什么？如何设置开发环境？如何测试服务？如何提交问题？如何部署它？
回答这些问题的常用方法是使用 README 文件。它是代码存储库中的文件，为开发人员提供了使用您的项目的起点。
README 应包含：
- API 的描述
- 技术参考和指南的链接
- 如何将项目设置为开发人员
- 如何测试项目
- 如何部署项目
- 依赖项管理
- 贡献指南
- 行为准则
- 许可证
- 致谢
在您的 README 中保持简洁；您不必解释每个方面，但要提供足够的信息，以便开发人员在熟悉您的项目后可以深入研究。
2. 技术参考
在 REST/JSON API 中，每个端点都是具有特定用途的特定功能。重要的是要有技术文档来指定每个端点；定义可能发生的描述、输入和输出；并为各种客户端提供示例。
REST/JSON 有一个名为 OpenAPI 的规范标准，它可以指导您完成记录 API 所需的详细信息。OpenAPI 还可以为您的 API 生成演示文档。
3. 用法
您的 API 用户需要的不仅仅是技术规范。他们想知道如何在特定情况或案例中使用您的 API。大多数潜在用户都有问题，他们希望您的 API 能够解决它。
向用户介绍您的 API 的一个好方法是使用“入门”页面。这可以引导用户完成一个简单的用例，让他们快速了解您的 API 的优势。
总结
文档是任何成功 API 的关键组成部分。在创建文档时，请考虑入门、技术和用法这三个重点领域——涵盖这些方面，您将拥有一个文档完善的 API。
验证
API 开发中最常被忽视的方面之一是验证。验证是验证来自外部来源的输入的过程。这些来源可能是发送 JSON 的客户端或响应您请求的服务。不仅仅是检查类型，确保数据是它应该是什么可以消除许多潜在的问题。了解您的边界以及您控制和不控制的内容是验证的重要方面。
最好的策略是在您的逻辑发生之前在边缘进行验证。当客户端向您的 API 发送一些数据时，请在您对该数据执行任何其他操作之前应用验证。确保电子邮件是实际的电子邮件地址，日期格式正确，字符串符合长度要求。
这个简单的检查将为您的应用程序增加安全性和一致性。此外，当您从服务（如数据库或缓存）接收数据时，请重新验证它，以确保返回的结果符合您的数据检查。
您可以始终手动验证或使用实用程序函数库，如 Lodash 或 Ramda。这些对于小型数据对象非常有用。像 Joi、Yup 或 Zod 这样的验证库效果更好，因为它们包含常见的验证，可以节省时间和精力，并创建非常易读的模式。如果您需要与语言无关的东西，请查看 JSON Schema。
总结
验证并不性感，但它可以节省大量时间，否则这些时间将用于故障排除和编写数据迁移脚本。不要犯信任您的客户端发送干净数据的错误；您不希望不良数据泄漏到您的业务逻辑或持久数据存储中。花时间验证您的 API 端点和服务响应。虽然这可能会在前期引起一些挫败感，但放松缰绳总比以后收紧缰绳容易得多。
测试
测试是软件开发的最佳实践，应作为首要的非功能性要求。定义测试策略对于包括 API 在内的任何项目都可能是一个挑战。始终了解您的约束并相应地定义您的策略。
集成测试是测试 API 最有效的方法之一。在这种模式中，开发团队创建一个测试来覆盖应用程序流程的某些部分，从一个特定点到另一个特定点。一个出色的集成测试流程包括测试 API 的入口点并模拟对服务的请求点。通过选择这两个点，您可以覆盖从 API 请求开始到服务请求的整个逻辑，并且模拟服务为您提供一个响应以返回给 API 响应。
虽然它使用模拟，但此方法允许您专注于逻辑层中的代码，而不依赖于后端服务或演示逻辑来运行测试。没有依赖项使得运行测试更加可靠、更易于自动化，并且更易于包含在您的持续集成管道中。
我用于集成测试的一种设置使用 Tape、Test-server 和 Fetch-mock。这些库使我能够针对 API 端点运行从请求到响应的隔离测试，Fetch-mock 捕获到持久层的出站请求。
总结
虽然所有类型的测试和类型检查都对 API 有益，但就有效性与构建和管理时间而言，集成测试提供了最大的好处。使用像 Fetch-mock 这样的工具可以在服务边界提供干净的模拟场景。
专注于基础知识
在您设计和构建应用程序和 API 时，请务必包含这四个基本要素。这些不是要考虑的唯一非功能性要求；其他要求包括应用程序监控、日志记录和 API 管理。即便如此，安全性、文档、验证和测试是为任何用例设计和构建成功 API 的关键重点。
评论已关闭。