揭秘正在驱动互联网的8个强大的API设计模式

解锁高性能平台背后的秘密，看看这些强大的API设计模式。

想象一下，构建一个能够无缝运行在数以百万计设备上的平台，每次都能快速可靠地服务用户。如果你知道这些强大系统背后的秘密并不是魔法，而是聪明的API设计，你会怎么想？今天，我们将深入探讨顶级公司用来保持数字世界运转的八种API设计模式。这些技术不仅仅是行业术语或抽象概念，而是你可以立即付诸实践的方法，配有真实案例和代码。

更多关于 API 基础知识的信息，请参阅 MDN Web Docs on HTTP 和 RESTful API 教程。

此处省略内容

1. RESTful：简单、可预测且功能强大

REST是许多现代系统的支柱。其设计原则是基于使用简单的HTTP方法——“GET”、“POST”、“PUT”、“DELETE”——以清晰和可预测的方式与资源互动。

为什么管用：

• 简单性： REST使得系统中的不同部分可以轻松进行通信。
• 可扩展性： 无状态设计使你可以轻松地进行水平扩展。
• 互操作性： 几乎所有的客户端都能够与RESTful API无缝协作。

Python 示例用 Flask:

这里有一个简单的快速示例，让你开始用 Flask 一个简单的 REST API（代表状态转移的 API）。

    从 flask 导入 Flask, jsonify, request  # 导入必要的模块

    app = Flask(__name__)

    # 用于演示目的的内存中 "数据库"
    users = [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"}
    ]

    @app.route('/users', methods=['GET'])
    def get_users():
        return jsonify(users)  # 获取所有用户

    @app.route('/users/<int:user_id>', methods=['GET'])
    def get_user(user_id):
        user = next((u for u in users if u["id"] == user_id), None)
        if user:
            return jsonify(user)
        return jsonify({"error": "用户不存在"}), 404  # 用户不存在

    @app.route('/users', methods=['POST'])
    def create_user():
        new_user = request.json
        new_user["id"] = users[-1]["id"] + 1 if users else 1
        users.append(new_user)
        return jsonify(new_user), 201  # 创建用户

    if __name__ == '__main__':
        app.run(debug=True)

点击进入全屏，点击退出全屏

资源如下:

• Flask 文档
• REST API 最佳实践

……

2. 查询语言 GraphQL：当一种尺寸不适合所有情况时

与 REST 不同的是，GraphQL 允许客户端请求他们确切需要的那些数据。这种灵活性可以减少数据获取过多或过少的情况，从而使您的应用程序更加高效。

为什么管用：

• 效率: 只发送请求的数据内容。
• 灵活性: 单一端点可以满足各种数据需求。
• 适应性: 在不影响现有查询的情况下，您可以自由演化模式。

使用图计算和 Flask 的 Python 示例：

    from flask import Flask
    from flask_graphql import GraphQLView
    import graphene

    class User(graphene.ObjectType):
        id = graphene.Int()
        name = graphene.String()

    class Query(graphene.ObjectType):
        users = graphene.List(User)

        def resolve_users(self, info):
            return [
                User(id=1, name="Alice"),
                User(id=2, name="Bob")
            ]

    schema = graphene.Schema(query=Query)

    app = Flask(__name__)
    app.add_url_rule(
        '/graphql',
        view_func=GraphQLView.as_view(
            'graphql',
            schema=schema,
            graphiql=True  # 启用 GraphiQL
        )
    )

    if __name__ == '__main__':
        app.run(debug=True)

全屏。退出全屏。

资源如下:

• GraphQL 官网
• Python 的 Graphene 点击访问

……

API编程指南：了解API、协议、安全和实现 | 更多详情请参考维基百科

(https://snappytuts.gumroad.com/l/fotcdz?layout=profile)

📌 课程名称：API编程：理解API、协议、安全和实现 | 使用维基百科
🔹 第一模块：基础知识 应用程序编程接口（API）简介 了解网络服务 超文本传输协议（HTTP）基础知识
🔹 第二模块：协议与数据格式 表示状态转移（REST） 简单对象访问协议（SOAP） 可扩展标记语言（XML） JavaScript对象表示法（JSON） 远程过程调用（RPC）
🔹 第三模块：高级通信技术 WebSocket通信 GraphQL简介及其工作原理 用于高效API的gRPC
🔹 第四模块：安全性 了解OAuth认证 JSON Web令牌（JWT）以实现安全的API访问 用于身份管理的OpenID Connect HTTPS对API安全的重要性以及传输层安全（TLS）
🔹 第五模块：架构与实现 微服务架构 实现可扩展API的无服务器计算 面向服务的架构（SOA） 企业应用集成（EAI）

快来看看 snappytuts.gumroad.com，别错过哦! 是一个提供教程的网站（一个网站）(点击图标)

此处省略内容

3. gRPC：加快对话速度

当性能和效率至关重要时，gRPC 表现出色。它采用协议缓冲区这种紧凑的二进制格式，以实现快速数据传输。

为什么管用：

• 性能: 快速的序列化和反序列化。
• 强契约: 强制执行严格的API合约。
• 多路复用: 支持双向流通信，实现并发。

Python 使用 gRPC 示例：

注意： 本示例假设你已经安装了 grpcio 和 grpcio-tools。

有关安装详情，请参阅 gRPC Python 快速入门指南。

在 .proto 文件（例如 user.proto）中定义你的功能/接口，比如：

syntax = "proto3";

//  the following is the definition of user service protocol
// 以下是定义用户服务的协议

package user;

service 用户服务 {
  rpc 获取用户 (用户请求) returns (用户响应) {}
}

message 用户请求 {
  // 获取用户信息的请求
  // Request for getting user information
  int32 id = 1;
}

message 用户响应 {
  // 获取用户信息的响应
  // Response for getting user information
  int32 id = 1;
  string name = 2;
}

1. 编写Python代码：

运行这个Python命令来使用grpc工具编译user.proto文件，将输出转换为Python代码，并生成Python特定的gRPC代码。gRPC是一个开源的RPC框架，Protocol Buffers（protobuf）是一种语言中立、平台中立、可扩展的序列化结构数据的方式。

1. 用Python部署服务器:

from concurrent import futures
import grpc
import user_pb2
import user_pb2_grpc

class UserService(user_pb2_grpc.UserServiceServicer):
    def GetUser(self, request, context):
        # 为了演示，返回一个固定的用户信息
        return user_pb2.UserResponse(id=request.id, name="Alice")

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    user_pb2_grpc.add_UserServiceServicer_to_server(UserService(), server)
    server.add_insecure_port('[::]:50051')
    server.start()
    server.wait_for_termination()  # 等待服务器终止

if __name__ == '__main__':
    serve()

资源如下:

• gRPC 官网
• gRPC Python 文档页面

由于源文本和初始翻译仅由"*"组成，无法确定具体含义，因此无法提供更准确、流畅和符合风格及术语的翻译。请提供有意义的文本以便更好地反映自然语言和文化背景。

——

4. 超媒体驱动的API：让数据指引方向

超媒体API（也称为HATEOAS）在响应中包含链接，使客户端无需查阅外部文档即可发现可用操作。

为啥有效：

• 自我探索: 客户可以通过链接了解更多可采取的操作。
• 韧性: 通过超媒体链接可以应对API结构的变化。
• 灵活性: 动态地引导客户完成应用程序的使用流程。

Python 示例代码：使用 Flask 实现 HATEOAS (超文本作为链接的 API):

    from flask import Flask, jsonify

    app = Flask(__name__)

    @app.route('/user/<int:user_id>', methods=['GET'])
    def get_user(user_id):
        # 在实际的应用中，这里会从数据库中查询用户信息
        user = {"id": user_id, "name": "Alice"}
        user["_links"] = {
            "self": f"/user/{user_id}",
            "update": f"/user/{user_id}/update",
            "delete": f"/user/{user_id}/delete"
        }
        return jsonify(user)  # 返回 JSON 格式的用户信息 (使用 jsonify 函数)

    if __name__ == '__main__':
        app.run(debug=True)

全屏 退出全屏

资源：

• HATEOAS 详解
• 构建超媒体API详解

此处省略内容

5. Webhooks 及事件驱动通信：实时通信

Webhooks 在事件发生时会立即向客户端推送数据，这非常适合需要实时响应的应用，并且通过避免不断轮询来减轻服务器负载。

为什么它有效：

• 即时反馈: 立即通知客户任何变更。
• 资源效率: 提高了资源效率，无需频繁轮询。
• 解耦: 使系统更松散地连接，更加稳健。

使用Flask接收并处理Webhook的Python示例

    从 flask 导入 Flask, request, jsonify  # 导入必要的模块

    app = Flask(__name__)

    @app.route('/webhook', methods=['POST'])
    def webhook():
        event = request.json
        print("Received webhook event:", event)
        return jsonify({"状态": "成功"}), 200

    if __name__ == '__main__':
        app.run(debug=True, port=5001)

全屏模式，开启/关闭

资源:

• 了解 Webhooks
• Webhooks 实践指南

……

6. API 网关：系统里的交通管理者

API网关充当客户端请求的唯一入口，负责处理路由、认证、负载均衡和分配以及缓存处理等任务。

为什么它有效？

• 集中管控: 应用一致的安全策略及监控。
• 简化客户端的交互: 客户端只需与一个端点交互。
• 灵活性: 网关可以灵活处理协议转换和版本管理。

使用Python和Flask模拟API网关的示例:

    from flask import Flask, request, jsonify
    import requests

    app = Flask(__name__)

    # 一个简单的代理端点，充当API网关
    @app.route('/api/<path:path>', methods=['GET', 'POST', 'PUT', 'DELETE'])
    def proxy(path):
        # 确定目标URL（演示中，将请求路由到本地服务）
        target_url = f'http://localhost:5002/{path}'
        response = requests.request(
            method=request.method,
            url=target_url,
            headers=request.headers,
            json=request.get_json(silent=True)
        )
        # 返回格式化的JSON响应，并传递状态码
        return jsonify(response.json()), response.status_code

    if __name__ == '__main__':
        app.run(debug=True, port=5000)

按全屏，按退出全屏

比如Kong和Tyk这样的可靠API网关，这些都是在实际应用中可以考虑采用的。

资源：

• API 网关的概念

• Kong API 网关平台

• • *

API编程指南：了解API、协议、安全与实现 | 参考维基百科

📌 课程标题：API编程：理解API、协议、安全和实现 | 使用维基百科作为参考资料🔹 第1模块：API编程基础 API简介 理解网络服务 超文本传输协议（HTTP）基础知识 🔹 第2模块：API协议和数据格式 表示状态转移（REST） SOAP（简单对象访问协议） XML（可扩展标记语言） JSON（JavaScript对象表示法） 远程过程调用（RPC） 🔹 第3模块：高级API通信技术 WebSocket通信技术 GraphQL介绍 与GraphQL相关的知识 gRPC用于高性能API 🔹 第4模块：API安全 了解OAuth认证 使用JWT进行安全的API访问 OpenID Connect用于身份管理 HTTPS对API安全的重要性 传输层安全（TLS） 🔹 第5模块：架构和实现模式 微服务架构 无服务器计算用于可扩展API 面向服务的架构（SOA） 相关的知识 企业应用集成（EAI）相关知识

snappytuts.gumroad.com

---

7. 后端为前端 (BFF): 定制每个客户端的体验

移动应用、网络浏览器和桌面应用各不相同，它们有着各自独特的需要。BFF模式为每个客户端创建专门的API，确保每个客户端都能得到它所需要的。

为什么管用：

• 定制化服务: 为每个客户提供量身定制的数据格式。
• 职责分离: 各团队可以为不同的平台开发各自的后端。
• 性能优化: 通过只发送必要的信息来减少数据负载。

Python 示例代码：使用 Flask 构建的简单后端支持前端

    从 flask import Flask, jsonify

    app = Flask(__name__)

    # 移动客户端的接口
    @app.route('/mobile/user/<int:user_id>', methods=['GET'])
    def mobile_user(user_id):
        # 移动客户端可能需要更精简的数据
        user = {"id": user_id, "name": "Alice", "avatar": "https://example.com/avatar.png"}
        return jsonify(user)

    # 网页客户端的接口
    @app.route('/web/user/<int:user_id>', methods=['GET'])
    def web_user(user_id):
        # 网页客户端可能需要更详细的信息
        user = {
            "id": user_id,
            "name": "Alice",
            "email": "[e-mail]",
            "address": "123 Main St",
            "偏好设置": {"主题": "dark", "通知": True}
        }
        return jsonify(user)

    if __name__ == '__main__':
        app.run(debug=True, port=5003)
    # 以调试模式运行，端口为5003

全屏 退出全屏

资源:

• 前端后端模式

• 为多个客户端设计的API

• • *

8. 版本管理和合约演变：使您的 API 未来无忧

变化不可避免。版本管理可以让您的API在不破坏现有集成的条件下逐步演进。这种做法支持在引入新功能或改进时平滑过渡。

它为什么管用：

• 稳定性: 多个版本确保现有应用持续运行。
• 灵活性: 在新版本中尝试新功能。
• 管控: 逐步淘汰过时的做法，同时保持系统的稳定。

使用 Flask 的 Python API 版本管理示例

    从 flask 导入 Flask, jsonify  # 导入必要的模块

    app = Flask(__name__)

    # API 的第一个版本
    @app.route('/api/v1/users', methods=['GET'])
    def get_users_v1():
        users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
        return jsonify(users)

    # API 的第二个版本，包含额外数据
    @app.route('/api/v2/users', methods=['GET'])
    def get_users_v2():
        users = [
            {"id": 1, "name": "Alice", "email": "[e-mail]"},
            {"id": 2, "name": "Bob", "email": "[e-mail]"}
        ]
        return jsonify(users)

    如果 __name__ == '__main__':
        app.run(debug=True, port=5004)  # 启动应用并监听端口5004

全屏模式；退出全屏

资源：

• API 版本策略

• API 的演进与兼容性

• • *

把一切都汇总起来

今天我们使用的互联网是基于每秒都在发生的无数互动建立起来的。这八种 API 设计模式不仅不只停留在理论层面，它们还是实际构建高性能系统的基石。无论你是刚开始学习还是在完善现有的平台，这些模式都能为你提供清晰、可行的步骤来提升你在 API 上的游戏水平。

花点时间思考一下你当前的 API 策略。REST API 是否可以从版本控制中获益？GraphQL 的精准数据获取是否可以减少你的数据传输量？也许实现一个 API 网关或专用的 BFF（Backend for Frontend）可以简化你的客户端交互。选择权在你，改进的空间非常大。

接下来：

• 尝试提供的代码示例。
• 通过查看链接的资源来加深理解。
• 从小处开始，逐步引入一个新的模式，观察性能上的提升。
• 随着信心和经验的增长，逐渐改进你的系统。

在快节奏的技术世界中，停滞不前并不是一个选项。借助这八种 API 设计模式，你将能够不断推动前进和创新，并建立不仅能满足当前需求，还能为未来的突破铺路的系统。拥抱这些模式，见证你的平台转型为一个强大的、高性能引擎，让用户保持参与并使系统运行顺畅。

记得: 未来由明智的设计选择决定——今天就做出你的选择吧！

想了解更多和获取灵感，可以看看我们关于API设计模式和现代Web API的构建的精选列表。

现在就开始写代码吧——互联网背后的秘密可能就在你接下来设计的那个接口里！

---

可以收藏这份指南并与你的团队一起分享。祝你编程愉快！

---

API编程：理解API、协议、安全及实现方法 | 参考维基百科

📌 课程标题：API 编程：了解 API、协议、安全和实现 | 使用维基百科介绍
🔹 模块 1：API 编程基础 应用程序编程接口 (API) 介绍 网络服务基础知识 超文本传输协议 (HTTP) 基础
🔹 模块 2：API 协议和数据格式 表示层状态转移 (REST) 简单对象访问协议 (SOAP) 可扩展标记语言 (XML) JavaScript 对象表示法 (JSON) 远程过程调用 (RPC)
🔹 模块 3：高级 API 通信技术 WebSocket 通信 GraphQL 介绍 gRPC 高性能 API
🔹 模块 4：API 安全性 了解 OAuth 身份验证 JSON Web 令牌 (JWT) 用于安全的 API 访问 OpenID Connect 身份管理和认证 HTTPS 对 API 安全的重要性 传输层安全协议 (TLS)
🔹 模块 5：架构和实现模式 微服务架构 无服务器计算以支持可扩展 API 面向服务的架构 (SOA) 企业应用集成 (EAI)

snappytuts.gumroad.com