API 规划指南：代码优先 VS 设计优先方法

想象一下，你是一位建筑师，站在空旷的土地上。你不会在没有蓝图的情况下就开始砌砖，对吧？同样的原则也适用于API开发。我过去使用代码优先的方法，先编写代码，然后在之后再编写文档，直到我学习了设计优先的方法。设计优先的方法是在编写任何代码之前创建一个详细的API定义。

本指南概述

在我们深入探讨之前，让我们规划一下我们的目标。可以把这看作是你的API规划路线图：

• 了解API规划的基础知识
• 探索两种不同的方法
• 做出明智的选择
• 创建你的API计划

你将学到什么：

1. API规划包括什么
2. 代码优先方法
3. 设计优先方法
4. 代码优先和设计优先的比较
5. 如何选择正确的方法
6. API规划的实际步骤

API规划包括什么

优秀API的基础

API规划不仅仅是关于技术规范——它也是关于构建其他人会喜欢使用的产品。这就像设计一栋房子，每个房间都有其用途，并与其他房间逻辑地连接起来。

需要回答的关键问题：

• 消费者是谁？（前端开发人员、第三方合作伙伴等）
• 它支持哪些操作？（CRUD操作、集成等）
• 如何确保其安全性？（身份验证、速率限制等）

规划的艺术

将API规划比作绘制杰作：

• 代码优先就像不打草稿直接作画
• 设计优先就像先规划好构图

代码优先方法

代码优先方法是指直接跳入编码，在编写API结构文档或设计之前创建功能。当我开始构建API时，我是一个代码优先的拥护者。以下是我学到的东西：

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

快速提示 ✨：代码优先适用于原型，但在进行过程中要记录你的决策！

工作原理

• 从后端开发和模型开始。
• 根据你的数据库结构构建API端点。
• 在实现后编写API文档。

优点

• 更快的原型设计：非常适合小型团队或个人项目。
• 直接实现：专注于构建功能，无需前期规划。

挑战

• 设计不一致：如果涉及多个开发人员，API可能缺乏一致性。
• 迭代困难：开发后进行重大更改可能代价高昂。

设计优先方法

设计优先方法强调在编写任何代码之前规划和定义API的结构。它让每个人都步调一致。在商定API定义后，利益相关者（例如测试人员和技术编写者）可以与开发人员并行工作。

工作原理

• 使用Swagger/OpenAPI等工具设计API模式。
• 定义端点、请求/响应格式和验证。
• 与利益相关者分享设计以获得反馈。
• 在设计最终确定后开始开发。

优点

• 协作：促进利益相关者尽早反馈。
• 一致性：确保端点的一致性。
• 模拟API：允许前端团队使用模拟响应更早地开始集成。

挑战

• 前期工作量：初始设计需要时间。
• 需要专业知识：开发人员必须熟悉设计工具和最佳实践。

代码优先与设计优先：比较

代码优先

• 速度：对于简单的项目更快。
• 协作：在初始阶段有限。
• 一致性：这可能因端点而异。
• 灵活性：对于单独开发很容易。
• 可扩展性：这可能难以扩展。

设计优先

• 速度：由于前期规划而较慢。
• 协作：鼓励早期团队协作。
• 一致性：确保标准化设计。
• 灵活性：非常适合团队或公共API。
• 可扩展性：设计时考虑了可扩展性。

如何选择正确的方法

如果满足以下条件，请选择代码优先：

• 你正在构建一个快速的概念验证或内部API。
• API使用者是一个单一的小型团队。
• 你优先考虑速度而不是设计。

如果满足以下条件，请选择设计优先：

• 你的API面向外部使用者或多个团队。
• 协作和一致性是优先事项。
• 你正在构建公共API或长期API。

API规划的实际步骤

步骤1：定义API的目的

在深入研究端点和方法之前，请回答以下基本问题：

• 你的API解决了什么问题？
• 你的目标用户是谁？
• 你必须提供哪些核心功能？
• 你的非功能性需求是什么？

示例目的陈述：

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

步骤2：识别核心资源

将资源视为API中的名词。对于我们的电子商务示例：

主要资源：

• 产品
• 库存
• 仓库
• 库存变动

资源关系：

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

步骤3：定义操作

现在考虑用户需要对这些资源执行哪些操作（动词）：

<code>此API使电子商务平台能够实时管理多个仓库的库存，确保准确的库存水平并防止超卖。</code>

步骤4：规划数据模型

定义清晰一致的数据结构：

<code>产品
  └── 库存
       └── 仓库
            └── 库存变动</code>

步骤5：规划身份验证和安全性

从一开始就考虑安全性：

• 身份验证方法
• 授权级别
• 速率限制
• 数据加密
• 输入验证

步骤6：编写API文档

创建全面的文档：

API概述

• 目的和范围
• 入门指南
• 身份验证详细信息

端点文档

• 资源描述
• 请求/响应格式
• 示例调用
• 错误处理

用例

• 常用场景
• 集成示例
• 最佳实践

结论

代码优先和设计优先方法在API开发中都很有价值。关键是选择符合项目需求、团队规模和长期目标的方法。最终，无论你选择代码优先还是设计优先方法，目标都是创建一个开发人员喜欢使用的API。有时，旅程不如目的地重要，但拥有一张好的地图可以使旅程更容易！

展望：CollabSphere案例研究

在我们即将推出的博客系列中，我们将通过构建CollabSphere（一个实时聊天系统）将这些原则付诸实践。你将亲眼目睹我如何将代码优先项目转变为设计优先杰作。

即将推出的内容预览：

• 从头设计聊天API
• 创建全面的API文档
• 实现实时功能
• 处理身份验证和安全性

以上是API 规划指南：代码优先 VS 设计优先方法的详细内容。更多信息请关注PHP中文网其他相关文章！