以下有一些问题：你是如何使用 Google、Apple 或 Microsoft 账号登录应用的？如何使用 Paystack 或 PayPal 进行在线支付？像 Facebook 和 Instagram 这样的应用是如何共享信息和通知的？

答案是：它们使用 API。这些是推动移动和 Web 开发以及各种应用程序（包括云服务、物联网设备、桌面软件等）的强大工具。

API 实现了应用之间的通信，促进了数据交换和验证。

在本文中，你将了解 API 的所有内容：不同类型、它们的架构以及不同架构之间的权衡。

我们将涵盖以下内容：

• 什么是 API？

  • API 如何工作？

  • 为什么 API 很重要？

• API 类型

  • 开放 API

  • 合作伙伴 API

  • 内部 API

  • 组合 API

• API 架构类型

  • REST API

  • SOAP API

  • GraphQL API

  • gRPC API

• 如何选择 API 架构

• 结论和未来趋势

这篇文章非常适合于 Web 和移动开发初学者，以及希望简要了解 API 及其如何运作的开发者。

什么是 API？

API 代表应用程序编程接口。它是一组规则和协议，让不同的软件系统相互通信。API 定义了应用程序如何请求服务和交换数据，充当客户端和服务器之间的明确契约。

API 将复杂的代码简化为简单的命令，让开发人员可以连接系统并使用内置功能，而无需了解所有的内部工作原理。

API 如何工作？

想象一下有一家餐馆：顾客（客户端）通过服务员（API）点餐，然后服务员通知厨房（服务器）。厨房备餐后通过服务员传递给顾客。就像服务员一样，API 处理请求和响应，让顾客在无需了解厨房操作细节的情况下享受餐点。

一个更实用的例子是当你在线购买订阅时，你的支付信息通过其支付 API 安全发送至 Paystack。API 是一个中间人，它获取你的请求，验证并处理你的银行支付信息，然后在不直接暴露敏感数据的情况下返回确认给网站。

从技术上讲，客户端向服务器发起请求，指定要获取数据还是执行某个流程。接收并认证该请求后，API 会执行所需操作。随后，API 向客户端发送响应，包括请求的结果（成功或失败）和任何请求的数据元素。

为什么 API 很重要？

API 在软件开发中至关重要，因为它们使得连接不同的应用程序和服务更加容易。它们允许你整合外部功能，而无需从头开始构建所有内容，通过标准化命令节省时间并降低复杂性。

对于用户来说，API 还可以提高安全性和用户体验。它们作为安全网关，过滤应用和外部服务之间的数据交换，保护敏感信息，同时确保流畅、可靠的互动。

API 类型

API 的类型主要根据其可访问性和使用情况进行分类。API 有四种类型，分别是：

1. 开放（公共）API

2. 合作伙伴 API

3. 内部（私有）API

4. 组合 API

开放 API

开放 API 是向公众提供的 API。这就鼓励开发者、组织和其他人使用它们来开发应用程序，将其集成到他们的服务中，并加以改进。开放 API 提供了通过互联网访问数据或服务的标准化接口。

一些非常实用的开放 API 包括：

• TradeWatch —— 实时金融市场数据

• SerpAPI 的搜索 API —— 实时谷歌搜索引擎结果页 API

• TwitterApi.io —— 访问实时和历史数据

• Instagram 帖子生成器 —— 使用流行 IG 页面模板生成帖子

合作伙伴 API

合作伙伴 API 与特定的商业伙伴共享，通常需要身份验证和协议。它们为企业和应用程序执行重要功能。

例如，像 Paystack 这样的支付 API 直接与服务提供商和银行平台通信，以处理产品和服务的支付。

内部 API

内部 API 用于组织内部的通信。它们能够实现集成并简化内部流程。内部团队使用 API 在其应用程序之间访问和共享数据。API 不对公众开放，以确保敏感的业务逻辑保持安全。

一个例子是公司内部 API，它连接其人力资源、工资单和项目管理系统。

复合 API

复合 API 将多个 API 调用组合为一个请求。在微服务架构中，它们非常重要，因为单个操作可能需要从多个服务中获取数据。一次 API 调用会触发对多个底层 API 的请求，然后复合 API 会组合这些响应并返回一个统一的结果。

例如，一个电子商务平台可能会使用复合 API 来一次性获取产品详情、定价和库存信息，减少延迟并简化集成过程。

API 架构类型

根据使用场景、可扩展性、安全性和可访问性，API 的结构各有不同。构建 API 的方式有多种，但我们将仅关注Web开发中最为流行的架构风格，它们包括：

1. REST

2. SOAP

3. GraphQL

4. gRPC

REST API

表述性状态转移（REST）是一种使用 HTTP 方法（POST、GET、PUT、DELETE）在基于资源的 URI 上执行 CRUD（创建、读取、更新、删除）操作的架构风格。

REST API 使用像 Express.js（Node.js）、Django/Flask（Python）、Spring Boot（Java）这样的框架构建。

关键组件

1. 资源和端点：

   • API 公开的实体可以包括任何内容：用户、产品、文档等。

   • 每个资源由唯一的 URI（统一资源标识符）标识。

2. HTTP 方法：

   • GET：获取资源。

   • POST：创建新资源。

   • PUT：更新现有资源。

   • DELETE：删除资源。

   • PATCH：部分更新现有资源。

3. 数据表示：

   • 资源可以有多种表示形式（例如，JSON，XML）。

   • API以请求的表示形式响应，允许对数据进行结构化和解析。

4. HTTP 标头和查询参数：

   • HTTP 标头提供有关请求或响应的附加信息。

   • 它们可以用于身份验证、内容协商和其他用途。

5. 无状态：

   • 客户端到服务器的每个请求都必须包含理解和处理请求所需的所有信息。

   • 服务器在请求之间不存储任何客户端状态。

其他显著的组件包括可缓存性、HTTP 状态和 HATEOAS。这些组件共同定义了 RESTful 系统的结构和行为，支持客户端与服务器之间的无缝高效通信。

操作概述

REST API 通过唯一的 URI 公开资源，并允许客户端使用 HTTP 方法（如 GET、POST、PUT、DELETE 和 PATCH）执行操作。客户端可以请求各种格式的数据，如 JSON 或 XML，并通过 HTTP 头和查询参数包含附加细节。

每个请求都是无状态的，包含处理所需的所有信息，而不依赖于存储的客户端数据。API 还使用 HTTP 状态码、可缓存性和 HATEOAS 管理响应并指导进一步的交互，确保客户端和服务器之间的无缝高效通信框架。

实际示例和真实案例

为了说明 REST API 在实践中的工作原理，我们以一个允许用户管理图书集合的图书 API 为例。我们的示例 API 是使用 NodeJS 和 ExpressJS 框架创建的。这里我们不解释这些框架的具体工作原理，因为这超出了本文的范围。所以如果你不了解下面代码的语法，不用担心，只需关注 请求 和 响应 逻辑。

此 API 遵循 REST 原则，使用标准 HTTP 方法执行 CRUD（创建、读取、更新、删除）操作：

const express = require("express"); const bodyParser = require("body-parser");
const app = express(); app.use(bodyParser.json());

const app = express();
app.use(bodyParser.json());

// 虚拟数据库
let books = [
  { id: 1, title: "The Pragmatic Programmer", author: "Andy Hunt" },
  { id: 2, title: "Clean Code", author: "Robert C. Martin" },
];

// 获取所有书籍（客户端请求，服务器响应）
app.get("/books", (req, res) => res.json(books));

// 新增一本书（客户端发送数据，服务器更新数据库）
app.post("/books", (req, res) => {
  const newBook = { id: books.length + 1, ...req.body };
  books.push(newBook);
  res.status(201).json(newBook);
});

// 更新一本书
app.put("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  if (book) {
    Object.assign(book, req.body);
    res.json(book);
  } else {
    res.status(404).json({ message: "Not found" });
  }
});

// 删除一本书
app.delete("/books/:id", (req, res) => {
  const index = books.findIndex((b) => b.id === parseInt(req.params.id));
  if (index !== -1) {
    books.splice(index, 1);
    res.json({ message: "Deleted" });
  } else {
    res.status(404).json({ message: "Not found" });
  }
});

app.listen(3000, () => console.log("API running on port 3000"));

此代码的操作流程如下：

• 客户端发送请求：用户（或前端应用）通过使用诸如 GET，POST，PUT 或 DELETE 等 HTTP 方法请求数据。例如：GET /books 请求所有书籍，或 POST /books 将新书提交到数据库。

• 服务器处理请求：服务器接收请求，查找数据（例如，从数据库或内存数组中查找），并进行处理。

• 服务器返回响应：服务器返回包含请求数据或确认消息的 JSON 响应。示例如下：

[
  { "id": 1, "title": "The Pragmatic Programmer", "author": "Andy Hunt" },
  { "id": 2, "title": "Clean Code", "author": "Robert C. Martin" }
]

• 客户端接收并使用数据：前端或其他服务使用 API 响应，并相应地显示或处理数据。

团队将 REST API 用于 Web 服务、移动应用程序和云集成。社交媒体平台获取帖子，电子商务网站检索产品详情。支付网关处理交易，天气应用程序访问实时预测。REST 的简单性和可扩展性使其成为公共和内部 API 的首选。

SOAP APIs

简单对象访问协议（SOAP）使用 XML 进行消息传递，并包括用于安全、事务和错误处理的内置标准。其正式约定由 WSDL（Web 服务描述语言）定义。

这种架构通过 WS-Security（Web Services Security）和事务管理等功能优先考虑安全性和可靠性，使其适合需要严格标准和强大错误处理的复杂企业应用程序。

SOAP APIs 是使用诸如 Apache CXF、.NET WCF 和 JAX-WS（Java）等框架或工具创建的。

关键组件

1. SOAP envelope（SOAP 封套）：

   • 这是 SOAP 消息的根元素，定义了 XML 文档的整体结构。

   • 它包含 SOAP Header（SOAP 标头）和 SOAP Body（SOAP 主体）。

2. SOAP body（SOAP 主体）：

   • 该部分包含在客户端和服务器之间交换的实际数据。

   • 它包括请求或响应消息，这些消息通常被构造为 XML 元素。

3. WSDL（Web 服务描述语言）：

   • 这是一个描述 Web 服务的 XML 文档，包括其操作、消息格式和数据类型。

   • 它充当客户端和服务器之间的合同，概述如何与 API 交互。

4. SOAP processor（SOAP 处理器）：

   • 这是处理 SOAP 消息的软件组件。

   • 它解析 XML 文档，提取相关数据，并执行请求的操作。

另外，还有 SOAP Endpoint（SOAP 端点），即 SOAP 服务可被访问的 URL，以及 XML Schema (XSD)，定义了 SOAP 消息的 XML 结构和数据类型。

操作概述

SOAP APIs 通过将数据封装在由 SOAP 封套定义的基于 XML 的结构中运行，该信封包含用于元数据的标头和用于实际请求或响应信息的主体。主体承载交换数据，而 WSDL 文档则作为契约，详细说明服务的操作、消息格式和数据类型。

SOAP 处理器随后解析 XML，提取相关数据，并根据附带的 XML 模式 (XSD) 定义的规则执行请求的操作。与服务的通信通过特定的 SOAP 端点进行，确保了 Web 服务交互的标准化、互操作框架。

实际例子和真实用例

为了说明 SOAP APIs 及其实际工作原理，我们考虑一个基于 SOAP 的银行服务 API，提供用于管理账户和交易的安全操作。SOAP APIs 使用 XML 消息传递，确保系统间的安全和结构化通信。创建 SOAP API 和 XML 消息传递超出了本文的范围，因此我们将在此重点讨论请求和响应逻辑。

如何运作：

• 获取账户信息: 客户端发送一个 XML 请求以获取用户的账户详情：

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bank="http://example.com/bank">
   <soapenv:Header/>
   <soapenv:Body>
      <bank:GetAccountDetails>
         <bank:AccountNumber>123456789</bank:AccountNumber>
      </bank:GetAccountDetails>
   </soapenv:Body>
</soapenv:Envelope>

服务器以包含账户详细信息的 XML 消息进行响应：

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <GetAccountDetailsResponse>
         <AccountNumber>123456789</AccountNumber>
         <Balance>5000.00</Balance>
         <Currency>USD</Currency>
      </GetAccountDetailsResponse>
   </soapenv:Body>
</soapenv:Envelope>

• 处理转账: 客户端提交一个带有认证详情的转账请求：

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                      xmlns:bank="http://example.com/bank">
       <soapenv:Header/>
       <soapenv:Body>
          <bank:TransferFunds>
             <bank:FromAccount>123456789</bank:FromAccount>
             <bank:ToAccount>987654321</bank:ToAccount>
             <bank:Amount>100.00</bank:Amount>
             <bank:Currency>USD</bank:Currency>
          </bank:TransferFunds>
       </soapenv:Body>
    </soapenv:Envelope>
  

  如果成功，服务器返回一个确认响应：

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
       <soapenv:Body>
          <TransferFundsResponse>
             <Status>Success</Status>
             <TransactionID>TXN987654</TransactionID>
          </TransferFundsResponse>
       </soapenv:Body>
    </soapenv:Envelope>
  

银行、医疗保健提供者和政府机构使用 SOAP 提供安全、可靠的 API。金融机构以严格的身份验证处理交易，而医疗系统在遵从法规下交换患者数据。航空公司依赖 SOAP 进行预订和售票，确保跨系统的一致数据完整性。

GraphQL API

GraphQL 是一种由 Facebook 开发的用于 APIs 的查询语言和运行时。它允许客户端在一个请求中精确地请求所需的数据，减少过度获取和不足获取。

关键组件

1. 模式: 这是 GraphQL API 的核心。它定义了数据的结构，包括对象类型、其字段及其关系。它作为客户端和服务器之间的契约，指定可以查询的数据。

2. 类型: 这些定义了数据中对象的结构。它们指定每个对象拥有的字段及这些字段的数据类型。

3. 字段: 这些是可以在一个对象上查询的独立数据片段。

4. 查询: 这些是客户端请求以检索数据。它们指定客户端希望恢复的字段。

5. 变更: 这些是客户端请求以修改数据（创建、更新或删除）。

6. 解析器: 这些是为模式中每个字段获取数据的函数。它们将 GraphQL 模式连接到底层数据源。

7. 订阅: 这些启用实时更新。客户端可以订阅特定事件，服务器将在事件发生时推送更新。

操作概述

GraphQL 定义了一个指定可用数据类型及其关系的 schema。然后，客户端构建查询或变更，精确请求所需数据字段。GraphQL 服务器处理这些请求，使用解析器从后端源获取数据。

服务器根据模式验证请求，执行解析器，并返回仅包含请求数据的 JSON 响应。客户端可以建立实时更新的订阅，使服务器在数据改变时推送数据。这种方法最小化了过度获取和不足获取，提高了数据检索的效率和灵活性。

实际示例和真实用例

让我们通过一个由 GraphQL 驱动的电子商务 API 来实际探讨 GraphQL API 的工作原理。此 API 可以高效地获取产品详情、评论和库存可用性。服务器是使用 NodeJS 和 Apollo Server 创建的。创建服务器超出了本文的范围，因此我们将专注于 Schema（关系数据库是如何构建和可视表示的）及 请求 和 响应 逻辑。

1. 模式:

# Schema (schema.graphql)

type Product {
  id: ID!
  name: String!
  description: String
  price: Float!
  inventory: Int!
  category: String!
}


```markdown
type Mutation {
  createProduct(name: String!, description: String, price: Float!, inventory: Int!, category: String!): Product!
  updateProductInventory(id: ID!, inventory: Int!): Product!
}

这个模式定义了数据类型（Product、Query、Mutation）并指定了可用的查询（product、products）和变更操作（createProduct、updateProductInventory）。它使用了 GraphQL 类型系统（String、Int、Float、ID、[ ]、!）

2. 请求和响应

   • 获取产品数据 - 客户端请求特定的产品字段（例如，名称、价格和描述）：

     query {
       product(id: "123") {
         name
         price
         description
       }
     }
     

     如果请求成功，服务器仅返回请求的数据：

     {
       "data": {
         "product": {
           "name": "无线耳机",
           "price": 99.99,
           "inStock": true
         }
       }
     }
     

   • 创建一个新产品：

     mutation {
       createProduct(name: "鼠标", price: 30, inventory: 100, category: "电子产品") {
         id
         name
         price
       }
     }
     

   • 更新产品信息：

     mutation {
       updateProduct(id: "123", price: 89.99) {
         name
         price
       }
     }
     

     如果成功，服务器返回更新后的详细信息：

     {
       "data": {
         "updateProduct": {
           "name": "无线耳机",
           "price": 89.99
         }
       }
     }
     

像 Facebook 和 Shopify 这样的公司使用 GraphQL 来实现高效、灵活的 API。电子商务和社交应用程序只提取所需的数据，减少多余的数据获取。移动应用程序优化性能，而分析工具无缝聚合复杂数据。

gRPC APIs

远程过程调用（gRPC）是一种高性能的 RPC 框架，使用 HTTP/2 和协议缓冲序列化结构化数据。它支持同步和异步通信以及流功能。

HTTP/2 是 HTTP 的最新演进，具备二进制分帧、多路复用、标头压缩和服务器推送等令人兴奋的特性，以提高性能和减少延迟。gRPC 充分利用了这些功能，实现快速、高效、同时的通信，使其非常适合微服务和实时应用。

关键组件

1. 服务定义：在 .proto 文件中定义。它指定了所提供的服务和可用的 RPC 方法，充当客户端和服务器之间的契约。

2. 消息是使用协议缓冲区定义的数据结构，可以在系统之间高效地序列化和反序列化数据。

3. 存根：自动生成的客户端和服务器代码，使客户端可以像调用本地方法一样调用远程方法，并使服务器可以实现服务逻辑。

4. 通道：它们管理客户端和服务器之间的连接，处理底层网络通信。

5. RPC 方法：gRPC 支持不同类型的调用，包括一元（单请求-响应）、客户端流、服务器流和双向流，每种都适合不同的使用场景。

6. 拦截器和元数据：这些提供了附加额外功能的机制，例如通过将元数据附加到 RPC 调用来进行身份验证、日志记录和错误处理。

操作概述

gRPC 让开发者能够在 .proto 文件中使用协议缓冲定义服务契约和消息类型，作为可用 RPC 方法的蓝图。代码生成器生成客户端和服务器存根，允许像本地函数一样调用远程过程，同时通道管理基于 HTTP/2 的网络通信。

它支持一元、客户端流、服务器流和双向流以应对不同的数据交换模式。此外，还可以集成拦截器和元数据来进行身份验证和日志记录等任务，确保系统稳健、安全和高效。

实践示例和实际使用案例

让我们考虑一个使用 gRPC 快速在客户端（移动应用）和后端服务之间快速通信的打车应用。gRPC 使用协议缓冲（Protobuf）进行二进制序列化，而不是像 JSON 或 XML 这样的基于文本的格式。这使得网络通信显著更快且更高效。

1. .proto 文件定义了 API 结构：

syntax = "proto3";

service RideService {
  rpc RequestRide(RideRequest) returns (RideResponse);
  rpc StreamRideUpdates(RideUpdateRequest) returns (stream RideUpdate);
}

message RideRequest {
  string user_id = 1;
  string pickup_location = 2;
  string destination = 3;
}

message RideResponse {
  string ride_id = 1;
  string driver_name = 2;
  string car_model = 3;
}

message RideUpdateRequest {
  string ride_id = 1;
}

当客户端发送一个 RideRequest 时，它会使用 Protobuf 序列化为一个紧凑的二进制格式。这减少了负载大小，加快了传输速度，提高了效率。服务器会在处理之前将其反序列化为一个结构化的对象。

2. 请求和响应：

   • 请求乘车：客户端点击按钮发送乘车请求，其中包含：

     {
       "user_id": "U123",
       "pickup_location": "Central Park",
       "destination": "Times Square"
     }
     

     服务器响应司机的详细信息：

     {
       "ride_id": "R456",
       "driver_name": "John Doe",
       "car_model": "Toyota Prius"
     }
     

     你可能会好奇为什么请求和响应是以 JSON 格式显示的，因为 gRPC 并不使用像 JSON 和 XML 这样的基于文本的格式。gRPC 使用的压缩二进制流不像 JSON 那样可读，这是一个紧凑且高效的编码格式，需要通过 Protobuf 反序列化来理解。在压缩二进制流格式中，请求或响应看起来像这样：

     08 D2 04 12 0D 43 65 6E 74 72 61 6C 20 50 61 72 6B 1A 0B 54 69 6D 65 73 20 53 71 75 61 72 65
     

   • 实时流更新：一旦分配了乘车，服务器就会向客户端流式传输实时更新：

     {
       "ride_id": "R456",
       "status": "Driver on the way",
       "driver_location": "5th Avenue"
     }
     

公司使用 gRPC 来满足高性能、实时应用程序中对高效服务通信的需求。像 Google、Netflix 和 Dropbox 这样的科技巨头使用 gRPC 来实现可扩展的微服务。共享乘车应用程序会流式传输实时司机位置，而金融科技平台则管理安全、低延迟的交易。物联网系统和人工智能应用依赖 gRPC 来进行实时数据交换和高效交互。

如何选择API架构

选择一个 API 架构需要根据项目的具体需求平衡性能、可扩展性、易用性和安全性等多个因素。

REST 因其简单性和无状态设计而闻名，这有助于可扩展性和易用性，但其安全性主要依赖于外部措施，如 HTTPS 和适当的认证机制。

SOAP 尽管更复杂，但提供了强大的内置安全标准（如 WS-Security）和可靠的事务支持，使其适合于企业环境。

GraphQL 通过只允许客户端请求所需的数据，提供了高效的数据获取和高性能，但可能需要额外的安全措施，比如查询深度限制和服务器端的恰当认证。

gRPC 提供了卓越的性能，非常适合实时数据需求的微服务。它利用 HTTP/2 和 TLS 来实现安全、高效的通信，尽管它需要较长的学习曲线。

下表总结了这些架构的特点以及如何权衡：

结论和未来趋势

API 已成为现代软件开发中的基本组成部分，促进了不同应用程序之间的无缝通信和数据交换。它们的影响是不可否认的，从推动创新的公共 API 到简化内部流程的私有 API。

理解 REST、SOAP、GraphQL 和 gRPC 等不同的 API 架构，使开发人员能够根据特定需求选择最佳方法，在性能、可扩展性和易用性之间取得平衡。

展望未来，API 领域将迎来令人兴奋的变化。随着 AI 驱动的 API、去中心化架构和改进的安全措施的出现，我们将看到新的方式来构建和交互软件。API 标准的持续演变和低代码/无代码平台的增长使 API 开发变得更容易为所有人所用。

在云计算领域和 serverless 架构中，AWS API Gateway 是一款强大的工具，能帮助您搭建强大、安全且可拓展的 API。

在本教程中，首先我将介绍 API 网关是什么，并解释使用 API 网关的好处。接下来，我将展示如何创建、部署一个 Rest API, 并创建使用计划以提供 API 密钥。那么，我们现在就开始吧！

什么是 API 网关？

AWS API Gateway 是 Amazon Web Services (AWS) 提供的一项全托管服务，可帮助您轻松搭建、部署和管理任意规模的 API。

它充当应用程序的前门，允许您创建充当客户端和后端服务之间桥梁的 API，以便实现安全有效的通信。

为什么需要 API 网关？

AWS API Gateway 可为企业和开发者提供诸多好处，下方列出了一些使用 API 网关的好处。

可拓展性和高可用性

借助 AWS API Gateway，您可以更轻松地进行 API 拓展。通过底层基础设施自动拓展， AWS API Gateway 可以无缝处理流量高峰，以确保高可用性并避免服务中断。

安全与认证

API 网关提供强大的安全功能，包括内置的身份验证和授权机制。

它支持通过 IAM 角色对内部应用程序进行用户身份验证，通过 Cognito 对外部应用程序进行身份验证，并且支持自定义授权者。

与其他 AWS 服务集成

作为 AWS 生态系统的一部分， API 网关与一系列其他 AWS 服务无缝集成，这意味着您能利用 AWS Lambda 函数、用于用户管理的 AWS Cognito，以及用于监管和日志记录的 AWS CloudWatch 等其他功能。

API 生命周期管理

利用 API 网关，您能轻松对不同阶段的 API 进行版本控制、部署及管理。这简化了发布更新、测试新功能以及管理不同环境（比如开发、预生产和生产）的过程。

我希望现在您已经了解了 API 网关是什么以及它为何如此重要。接下来让我们一起来创建自己的 API 网关吧！

如何创建 AWS API Gateway

在本节中，我们将：

• 采用 GET 方法创建 Rest API
• 将其与简单的 hello world lambda 函数集成并进行部署

让我们从创建 lambda 函数开始吧

如何创建 AWS Lambda 函数

登录 AWS Management 控制台 并在控制台搜索栏中搜索 "Lambda"。然后，单击 Create Function 按钮。

选择 "Author from scratch" 选项，输入 lambda 函数名称，选择 "Python" Runtime，然后单击右下方的 Create Function 按钮。

函数创建成功后，请更新下方代码并部署更改：

import json

def lambda_handler(event, context):
    body = "Hello from 5minslearn!"
    statusCode = 200
    return {
        "statusCode": statusCode,
        "body": json.dumps(body),
        "headers": {
            "Content-Type": "application/json"
        }
    }

恭喜! 您已成功创建 AWS Lambda 函数，接下来让我们来创建 Rest API。

如何创建 Rest API 并将其与 AWS Lambda 集成

在搜索栏搜索 API Gateway，然后在 REST API 版块中单击 Build 按钮。

选择协议为 Rest，并在 Create new API 选项中选择 New API。在设置选项中输入您选择的 API 名称，并保留 Endpoint Type 的默认选项。然后，单击 Create API 按钮。

首先单击左上方的 Actions 按钮，然后单击 Method 并选择 GET 方法，再单击勾选图标。

选择 Lambda Function 作为 Integration type，并输入已创建的 Lambda 函数名称。然后，保存此函数。

单击保存后， 屏幕中将弹出 "Add Permission to Lambda Function"消息提示确认，这就意味着您将允许 API Gateway 调用 Lambda 函数（在本例中指的就是 "DemoFunction" Lambda 函数）。请同意确认，并继续下一步。

同意授权通过 API 网关调用 Lambda Function

单击 Test，您将来到一个新页面。单击 "Test" 按钮，此时您能在右侧面板上看到 Lambda 函数做出的响应。

在成功测试 API 后，您就能部署 API 了。要部署 API，请再次单击 Actions 按钮，然后单击 Deploy API。

此时屏幕上将弹出 Deploy API 的对话框，请选择 New Stage 作为 Deployment stage，并对其进行命名。然后，单击 Deploy 按钮。

单击页面顶部的 Invoke URL，您将看到 Lambda 做出的响应。

真棒! 我们已经成功创建了 Rest API，将其与 Lambda 函数集成并进行了部署。

但是，您可以通过市场中提供的多种服务来实现这个目标，那为什么要选择 AWS API Gateway 呢？

嗯，这是一个有趣的问题。首先，您可以利用 AWS API Gateway 为自己的 API 配置使用计划，而其中最突出的一点就是您无需为此编写任何代码。

现在就让我们来创建一个使用计划，生成一个 API 密钥，并仅通过在标头中传递 API 密钥来访问 Rest API。

如何创建 API Gateway 使用计划

在左侧边栏中单击 Usage Plans，然后单击 Create 按钮。输入您的计划名称，这里我选择了 "Basic"。根据您的需求在 Throttling 和 Quota 选项中输入相应数值，然后单击 Next。

单击 Add API Stage 按钮，并选择相应的 API 及其 Stage。然后，单击右上角的勾选图标，并选择 Next。

单击 "Create API Key and add to Usage Plan"，屏幕上将弹出一个对话框，请输入 API 密钥名称。而关于 API 密钥，我这里选择了 Auto Generate （自动生成），当然您也可以进行自定义。然后，单击 Save 按钮。

从侧边栏选择 Resources，单击已创建的 GET API，然后单击 Method Request。

在设置选项中，将 API Key Required 字段更新为 "true" 并单击勾选图标。更新后，务必点击 Actions 下拉菜单以部署更改。否则，变更将不会更新。

现在点击相同的 URL，你会发现神奇的事发生了。

Forbidden （禁止访问）！

因为现在我们的 API 层已受保护，您必须在标头中传递 API 密钥才能访问数据。

若未提供 API 密钥，则禁止访问。

现在单击侧边栏中的 Usage Plans，选择您的计划并导航至 API 密钥选项卡。

单击您在步骤 3 中创建的 API 密钥，然后单击 Show， 并复制此 API 密钥。

您必须在 'x-api-key' 标头中传递密钥。现在，让我们切换至终端来测试一下。

首先，测试一下在不传递 API 密钥的情况下 Rest API 的响应。打开终端，然后输入下方的 curl 命令。此时，您将再次看到“禁止访问”的消息。

curl --location --request GET '[enter your invoke url]'
--header 'Content-Type: application/json

终端中未提供 API 密钥的情况下禁止访问

现在再进行一次测试，在标头中传递 API 密钥，并运行下方 curl 命令：

curl --location --request GET '[your invoke url]' \
--header 'x-api-key: [your api key]' \
--header 'Content-Type: application/json' \
--data-raw ''

在 x-api-key 标头中传递 API 密钥时获取的数据

因为在标头中传递了 'x-api-key'，所以您能看到 Lambda 函数输出的结果。

真棒! 您已经成功创建了使用计划，生成了 API 密钥，并将其附加到 Rest API 方法中以及验证了集成。

总结

在本教程中，您学习了 AWS API gateway 是什么，以及如何为 Rest API 创建使用计划。

如果您想学习更多关于 AWS Services 的知识，可以订阅我的 email newsletter (https://5minslearn.gogosoon.com/) 并在社交媒体上关注我。

我将在这篇文章中分享在 Express 中构建强大的 REST API 的方法。首先，我会介绍构建 REST API 的一些挑战，然后提出一个使用开放标准的解决方案。

本文并非一篇关于 Node.js、Express.js 或 REST API 的介绍。如果你需要复习，请在深入研究本文内容之前查看这些链接。🤿

我喜欢 Node.js 那极具灵活性和易用性的生态。这个社区充满活力，并且你可以用你已经掌握的语言在几分钟内设置一个 REST API。

在应用的前后端使用相同的编程语言是一件很有价值的事。这使我们在浏览代码库时可以减少上下文切换，从而变得更轻松。全栈开发者可以快速切换技术栈，共享代码也变得轻而易举。

尽管如此，随着 MVP 成长为成熟的生产环境应用程序和开发团队规模的扩大，这种灵活性也带来了挑战。

使用 REST API 的挑战

无论你使用哪种技术栈，当代码库和团队规模增长时，都会面临许多挑战。

在本文中，我将描述通过 REST API 暴露业务逻辑的 Express.js 应用程序所带来的挑战，以小见大。

无论 API 消费者的性质如何（网页、移动应用、第三方后端），随着他们的成长，他们都可能面临以下一个（或多个）挑战：

1. ⚠️ 更难做出改变

在文档不够明确时，在 REST API 的任何一方进行修改都变得更加困难。

举个例子，假设你有一个 REST 端点，可以返回一个特定的用户的名字。在即将新增的功能中，你可能需要修改这个 API 使其返回年龄。这可能会潜在地破坏网络应用和移动应用。

你可以设置集成测试来一定程度上避免这个问题，但你仍然会严重依赖开发人员来手动覆盖所有的边界情况。这需要大量的时间和精力，而且你永远无法 100% 确定这些变化不会破坏应用程序。

2. 📜 缺少（及时更新的）文档

文档是构建 REST API 时的另一个敏感话题。我坚信在大多数情况下，代码本身应该足以代替一部分文档。

也就是说，REST API 在开发中会变得越来越复杂，检查代码中每个端点的安全性、参数和可能的响应也随之变得繁琐且耗时。这就减慢了开发的速度，也给 bug 进入系统留下了隐患。

即使团队致力于在一个独立于代码的文档中手动保持文档的更新，也很难 100% 确保它反映了代码的情况。

3. 📢 公共 API

这并不适用于所有的应用程序，但在某些情况下，一个应用程序可能需要向第三方暴露一系列的功能。对于这种情况，第三方有可能会在我们暴露的 API 之上构建核心功能。

这意味着我们不能以更新我们的私有 API 的同样速度来修改这些公共 API。一旦修改了公共 API，第三方应用程序可能会因此崩溃，而这正是我们应该不惜一切代价避免的事情。

公共 API 所暴露的内容应该是明确的，并且可以简单地进行开发，以限制内部和外部开发团队之间所需的来回沟通的数量。

4. ✍️ 手动集成测试

当应用程序的开发没有与之匹配的周密计划时，很有可能 API 所提供的内容和 API 消费者期望的内容被深埋在代码中。

对于仅有少量的内部端点的系统来说，这并不是一个大问题。但随着 API 接口数量的增长，修改现有的端点需要在整个系统中遵循面包屑，以确保消费者期望得到的东西与提供的东西是相等的。

这个问题可以通过对系统的不同部分之间进行集成测试来缓解。但是人工完成这件事的工作量非常巨大的，并且如果没做好的话，可能会在系统实际上不能正常工作的时候让开发人员误以为系统状态良好。

提出的解决方案

我们已经看到了构建 REST API 所带来的固有挑战。在下一节中，我们将使用开放标准构建一个示例 Express 项目，以解决这些挑战。

API 标准规范

前面部分描述的挑战已经存在很长时间了，所以面对这个问题，我们最好查看现有的解决方案，而不是重新发明轮子。

许多标准尝试对 REST API 进行规范化定义（RAML、JsonAPI、OpenAPI......）。这些项目的共同目标是使开发人员更容易定义他们的 API 行为，以便跨多种语言的服务器和客户端能够“共说一种语言”。

有了某种形式的 API 规范，可以解决许多挑战，因为在许多情况下，可以从这些规范自动生成客户端 SDK、测试、模拟服务器和文档。

一种我最喜欢的规范是 OpenAPI（原名 Swagger）。它有一个很大的社区，并且有很多用于 Express 的工具。这可能不是所有 REST API 项目中的最佳工具，因此请在为你自己的项目选择规范之前进行额外的研究，以确保该规范的工具和支持对你的项目有帮助。

示例的背景

在这个示例中，假设我们正在构建一个待办事项列表管理应用。用户可以通过访问一个 web 应用来获取、创建、编辑和删除待办事项，这些待办事项被保存在后端。

在这个例子中，后端使用一个 Express.js 应用程序，它将通过 REST API 暴露以下功能：

• 获取待办事项: [GET] /todos
• 创建待办事项：[POST] /todos
• 编辑待办事项：[PUT] /todos/:id
• 删除待办事项：[DELETE] /todos/:id

对于一个真实的待办事项管理应用来说，上面的功能有点过度简化，但这有助于展示我们如何在实际情况下克服上面提出的挑战。

实现

很好，现在我们已经介绍了 API 定义的开放标准和背景，让我们来实现一个 Express 待办事项应用，演示怎么解决前面的挑战。

我们将使用 Express 库 express-openapi 的 OpenAPI。请注意，这个库提供的高级功能（响应验证、认证、中间件设置......）超出了本文的范围。

你可以在这个仓库中找到演示的完整代码。

1. 初始化一个 Express 框架，并初始化一个 Git 仓库：

npx express-generator --no-view --git todo-app
cd ./todo-app
git init
git add .; git commit -m "Initial commit";

2. 将 express-openapi 引入我们的程序：

npm i express-openapi -s

// ./app.js

...

app.listen(3030);

...

// OpenAPI routes
initialize({
  app,
  apiDoc: require("./api/api-doc"),
  paths: "./api/paths",
});

module.exports = app;

3. 添加 OpenAPI 基础模型。

请注意，模型中定义了 Todo 的类型，将在路由处理程序中引用。

// ./api/api-doc.js

const apiDoc = {
  swagger: "2.0",
  basePath: "/",
  info: {
    title: "Todo app API.",
    version: "1.0.0",
  },
  definitions: {
    Todo: {
      type: "object",
      properties: {
        id: {
          type: "number",
        },
        message: {
          type: "string",
        },
      },
      required: ["id", "message"],
    },
  },
  paths: {},
};

module.exports = apiDoc;

4. 添加路由处理程序。

每个处理程序都声明它支持哪些操作（GET、POST ...），对每个操作的回调，以及该处理程序的 apiDoc OpenAPI 模型。

// ./api/paths/todos/index.js
module.exports = function () {
  let operations = {
    GET,
    POST,
    PUT,
    DELETE,
  };

  function GET(req, res, next) {
    res.status(200).json([
      { id: 0, message: "First todo" },
      { id: 1, message: "Second todo" },
    ]);
  }

  function POST(req, res, next) {
    console.log(`About to create todo: ${JSON.stringify(req.body)}`);
    res.status(201).send();
  }

  function PUT(req, res, next) {
    console.log(`About to update todo id: ${req.query.id}`);
    res.status(200).send();
  }

  function DELETE(req, res, next) {
    console.log(`About to delete todo id: ${req.query.id}`);
    res.status(200).send();
  }

  GET.apiDoc = {
    summary: "Fetch todos.",
    operationId: "getTodos",
    responses: {
      200: {
        description: "List of todos.",
        schema: {
          type: "array",
          items: {
            $ref: "#/definitions/Todo",
          },
        },
      },
    },
  };

  POST.apiDoc = {
    summary: "Create todo.",
    operationId: "createTodo",
    consumes: ["application/json"],
    parameters: [
      {
        in: "body",
        name: "todo",
        schema: {
          $ref: "#/definitions/Todo",
        },
      },
    ],
    responses: {
      201: {
        description: "Created",
      },
    },
  };

  PUT.apiDoc = {
    summary: "Update todo.",
    operationId: "updateTodo",
    parameters: [
      {
        in: "query",
        name: "id",
        required: true,
        type: "string",
      },
      {
        in: "body",
        name: "todo",
        schema: {
          $ref: "#/definitions/Todo",
        },
      },
    ],
    responses: {
      200: {
        description: "Updated ok",
      },
    },
  };

  DELETE.apiDoc = {
    summary: "Delete todo.",
    operationId: "deleteTodo",
    consumes: ["application/json"],
    parameters: [
      {
        in: "query",
        name: "id",
        required: true,
        type: "string",
      },
    ],
    responses: {
      200: {
        description: "Delete",
      },
    },
  };

  return operations;
};

5. 添加自动生成的文档，swagger-ui-express：

npm i swagger-ui-express -s

// ./app.js

...

// OpenAPI UI
app.use(
  "/api-documentation",
  swaggerUi.serve,
  swaggerUi.setup(null, {
    swaggerOptions: {
      url: "http://localhost:3030/api-docs",
    },
  })
);

module.exports = app;

这就是我们最终获得的效果：

这个 SwaggerUi 是自动生成的，你可以在 http://localhost:3030/api-documentation 访问它。

🎉 恭喜！

当你进行到文章的这里时，你应该创建好了一个完全可运行的 Express 应用程序，其与 OpenAPI 完全集成。

现在，通过使用在 http://localhost:3030/api-docs 中定义的模型，我们可以轻松生成测试、模拟服务器、类型，甚至客户端！

总结

我们只是浅浅涉猎了 OpenAPI 所能做到的事情。但是我希望这篇文章能够让你了解标准 API 定义模式是如何在可见性、测试、文档和整体置信度方面帮助构建 REST API 的。

谢谢你看到最后！

我目前正在构建 taggr，这是一个跨平台的桌面应用程序，它在帮助用户重新发现他们的数字记忆的同时保持他们的隐私。

Linux、Windows 和 macOS 平台上的 alpha 版本即将推出。请查看网页并登记，以免错过！

除了使用集群模式，还有各种各样扩展API的方式。在这篇教程中，我们将学习10种扩展Node.js API的方式。

我们经常会在处理项目的时候获取一些零散的知识以提高技能，必须通过不断地复习，才能将习得的技能应用到下次项目中。

这个方法一直奏效吗？我甚至不记得我昨天做了些什么。所以我写下了这篇教程，也是对自己知识的复盘。

我尝试记录下这些不常被提起扩展Node.js的方法。

本文提及的方法不一定是你最后的救命稻草，你可以在Node.js项目的任何阶段应用这些方法。

让我们来看看本文的内容：

1. 🚦使用节流
2. 🐢 优化数据库查询
3. ䷪ 使用断路器快速故障
4. 🔍 记录检查点
5. 🌠 使用Kafka而非HTTP请求
6. 🪝 小心内存泄露
7. 🐇 使用缓存
8. 🎏 使用连接池
9. 🕋 无缝扩展
10. 💎 OpenAPI兼容文档

使用节流

节流可以限制对服务器的访问，以防止请求过量。使用节流的好处非常明显：可以保护应用免受大量用户爆发的困扰，也可以防止拒绝服务攻击（Dos攻击）。

输入和输出的速率不匹配的时候，通常是应用节流机制的时候。特别是当入站流量远超过服务器可以（或者希望）处理的流量。

让我们通过图像来理解：

在应用程序和新闻推送服务器之间的第一个节点应用了节流：

1. 新闻推送服务（NFS）订阅了你的应用以发送通知。
2. 每秒向你的应用发送1000个请求。
3. 根据NFS的订阅计费计划，你的应用仅处理500个请求/秒。
4. 为前500个请求发送通知。

必须要注意的是，所有超过500个请求/秒以外的请求都会失败，需要NFS再次尝试发送请求。

当可以排队的时候，为什么要拒绝额外的请求？ 有以下理由：

1. 接受所有请求会使应用开始累积请求，这可能导致所有订阅你的应用的客户端出现单点故障（通过RAM/磁盘耗尽），包括NFS。
2. 你不应该接受超出客户订阅计划范围的请求（在我们的例子中是NFS）。

对于应用程序级别的速率限制，你可以使用Express.js API的中间件——express-rate-limit。对于网络级别的节流，你可以使用类似WAF的解决方案。

如果你使用的是发布-订阅机制，也可以限制消费者和订阅者。例如，你可以通过设置maxBytes选项来限制消费Kafka标签（topic）的字节数据。

优化数据库查询

有时你可能没有缓存数据，或者数据已经过期，查询数据成了唯一的选择。

发生这种情况时，请确保你的数据库做好了准备：第一步是拥有足够的RAM和磁盘IOPS（每秒输入输出量）。

其次，尽可能优化你的查询。对于初学者来说，做对这几件事很关键：

1. 查询时尽量使用索引字段，但不要过度索引。索引也有开销。
2. 对于删除，坚持软删除。如果需要永久删除，请推迟。（一个有趣的故事）
3. 在读取数据的时候，仅使用投影（projection）获取需要的字段。如果可以的话，去掉没有必要的元数据和方法。（例如，Mongoose提供lean)。
4. 尝试将数据库性能和用户体验分离。如果数据库上的CRUD可以在后台发生（即非阻塞），请执行此操作。不要让用户等待。
5. 使用更新查询直接更新所需字段。不要获取文档，更新字段，然后将整个文档保存回数据库。这会造成网络和数据库开销。

使用断路器快速故障

想象一下，你的Node.js应用程序出现突发流量，并且满足请求所需的外部服务器之一已关闭。你是否想在此后的每个请求中一直走死胡同？当然不！我们不想在注定要失败的请求上浪费时间和资源。

这就是使用断路器的核心思想：尽早失败、快速失败。

例如，如果100个请求中有50个失败，则在接下来的X秒内不允许对该外部服务器发出任何请求。它可以防止触发必然会失败的请求。

一旦线路复位，就允许请求通过。如果它们再次失败，则线路断开并重复循环。

可以查看Opposum以了解更多添加断路器的信息。你也可以在这里阅读更多关断路器的信息。

记录检查点

良好的日志记录设置可以帮助你快速发现错误。你可以创建可视化日志来了解应用程序的行为、设置警报和有效地调试。

你可以使用ELK stack来设置良好的日志记录和警报管道。

虽然日志记录是必不可少的工具，但很容易过度使用。如果记录所有内容，最终可能会耗尽磁盘IOPS，从而导致你的应用程序受到影响。

一个值得借鉴的经验是只记录检查点。

检查点可以是：

1. 当进入应用程序中的主控制流时以及在它们经过验证和清理之后的请求
2. 与外部服务/SDK/API交互时的请求和响应。
3. 对该请求的最终响应。
4. 为catch处理程序提供有用的错误消息（错误消息具有合理的默认值）。

另外： 如果一个请求在生命周期中经过多个服务器，你可以在日志中传递一个唯一ID，以跨服务器捕获特定请求。

使用Kafka而非HTTP请求

虽然存在HTTP请求的用例，但容易使用过度，请在不必要的时候避免使用HTTP请求。

让我们通过这个例子来理解：

假设我们要创建一个如Amazon一样的产品，这个产品包含两大服务：

1. 供应商服务
2. 库存服务

每当你收到来自供应商服务的新库存，就推送一个库存详情到Kafka标签。库存服务监听到这个标签，并且更新数据库以确认有新的补货。

请注意，你将库存数据推送到管道（pipeline）然后程序流，就可以继续其他的操作。程序会自动按照一定节奏消费库存服务。Kafka使服务解耦。

现在，如果你的库存服务出现了故障怎么办？如果是用HTTP请求就不容易处理。但如果使用Kafka，就可以重播预期的消息（例如使用kcat）。使用Kafka的话，数据被消费后不会丢失。

当某个商品重新回到库存，你可能希望向愿望清单包含这个商品的顾客推送消息。要实现这个功能，可以让通知服务和库存服务监听同样的标签。通过这种方式，就可以实现在不同的地方使用单个消息总线，并没有HTTP开销。

KafkaJS的开始页面分享了从Node.js应用的基础设置到上述功能的代码片段，我强烈推荐你查看，有很多内容值得研究。

小心内存泄露

如果你不编写保护内存安全的代码，并且不经常分析你的应用，很有可能造成服务器崩溃。

你可不希望自己的分析结果如下：

对于初学者，我建议：

1. 使用--inspect标志来执行 Node.js API。
2. 在Chrome浏览器打开chrome://inspect/#devices。
3. 点击 inspect > Memory tab > Allocation instrumentation on timeline。
4. 在执行一些应用功能。可以使用macOS的apache bench来同时发出多个请求，在终端执行 curl cheat.sh/ab查看怎么使用apache bench。
5. 停止记录并分析内存保持器。

如果发现任何大块的保留内存，请尝试将其最小化。这个话题相关的资源很多，你可以从谷歌搜索“如何防止 Node.js 中的内存泄漏”开始探索。

分析你的 Node.js 应用程序并寻找内存使用模式应该是常规做法。让我们把“分析驱动重构”（PDR）提上日程？

使用缓存避免过多的数据库查找

这么做的目的是不要每一次应用发出请求都连接一次数据库，使用缓存存储结果可以减少数据库的负载，提高应用性能。

有两种使用缓存的策略。

通过缓存写入可确保在发生写入操作时将数据插入数据库和缓存中。这可以使缓存保持相关，并带来更好的性能。缺点是因为不经常使用的数据也被存储到缓存中，所以缓存开销昂贵。

而在延迟加载中，数据仅在第一次读取时才写入缓存。第一次请求提供来自数据库的数据，但随后的请求使用缓存。它具有较小的成本，但增加了第一次请求的响应时间。

要决定缓存数据的TTL（或生存时间），请问自己：

1. 基础数据要多久更改一次？
2. 将过期数据返回给最终用户的风险是什么？

在允许的情况下，更长的TTL意味着更好的应用表现。

重要的是，为你的TTL添加一点增量。如果应用程序一时间收到大量流量，并且你的所有缓存数据立即过期，则可能导致数据库无法承受负载，从而影响用户体验。

最终TTL = TTL预估值 + 一点随机增量

TTL的计算

有许多缓存逐出的策略，保留默认值是一种有效且可接受的方法。

使用连接池

打开一个与数据库的独立连接开销很高。它涉及TCP握手、SSL、身份验证和授权检查等。

你可以利用连接池来取代独立连接。

一个连接池在任何给定时间都拥有多个连接。每当需要它时，池管理器都会分配任何可用/空闲连接。你可以跳过建立全新连接的冷启动阶段。

那么，为什么不最大化池中的连接数呢？因为它高度依赖于硬件资源。如果忽略这一点，可能会造成巨大的性能损失。

连接越多，每个连接的RAM越少，利用RAM的查询越慢（例如排序）。同样的原则也适用于磁盘和CPU。每个新连接都将被分配到资源。

你可以根据自己的需求调节连接数，对于初学者来说你可以在这里评估连接池的大小。

你可以在这里阅读连接池相关的内容。若你使用的是PostgreSQL，你可以使用node-postgres包。这是一个连接池的内置支持。

无缝扩展

当应用程序的用户群逐渐增长并且已经达到垂直扩展的上限时，你会怎么做？水平缩放。

垂直扩展意味着增加节点（CPU、内存等）资源，而水平扩展意味着增加更多的节点以平衡每个节点的负载。

如果你使用的是AWS，则可以利用自动扩展组（ASG），它根据预定义的规则（例如，当CPU利用率超过50% 时水平扩展服务器数量。

你可以通过提前规划行为来提前规划扩展和缩小的计划，以此来应对可以遇见的流量模式（如在世界杯期间的流媒体服务）。

准备好ASG后，在最前面添加负载均衡器将确保流量根据所选策略路由到所有实例（如round robin）。

PS： 预估单个服务器可以处理的请求（CPU、内存、磁盘等）并分配至少 30%以上的容量总不会错。

OpenAPI兼容文档

它可能不会直接影响扩展Node.js应用程序的能力，但我必须将其包含在列表中。如果你曾经做过API集成，你就知道为什么了。

在向前迈出一步之前，了解有关 API 的所有信息至关重要。它使设计的集成、迭代和推理变得容易，更不用说对开发速度的帮助。

确保为你的 Node.js API 创建 OpenAPI 规范（OAS）。

这使得你以行业标准的方式创建 API 文档。OAS充当单一的事实来源。如果定义得当，它会使与 API 的交互更加高效。

我在这里创建了一个API文档样本，你可以使用swagger inspector来监测任意API。

你可以在Swagger Hub dashboard找到所有API文档，以及创建一个新的文档。

行动起来吧！

我们研究了十个鲜为人知的扩展Node.js的最佳实践，以及如何开启每一个最佳时间。

现在轮到你对照这个清单并探索发现你的Node.js应用程序缺少了什么。

获取你的检查清单✨

希望这篇文章对你有所帮助，并在可扩展性方面为你提供了一些指导。这并不是所有最佳实践的详尽清单——我只是列出了这些我认为不常被提及的。

欢迎在Twitter上联系我。我很乐意听取你在使用其他最佳实践的经历和心得。

喜欢这篇文章吗？在这里获取更多后端提升小建议 💌。

想象一下，你刚买了一个新的家庭影院系统，你去设置它，首先要做什么？

谢天谢地，你有一本方便的设备手册来帮助你。你只需要按照手册中详细说明的步骤进行操作，然后就可以了。你的家庭影院系统已经准备好播放你喜欢的歌曲了。

就像设备手册如何指导你进行设置和安装一样，API文档可以帮助指导你完成配置API。

什么是API文档？

在深入研究API文档之前，让我简单解释一下什么是API以及它的基本功能。

API是Application Programming Interface（应用编程接口）的首字母缩写。

无论你是初级编码员还是高级开发人员，你都会在你的软件开发旅程中经常遇到这个术语。它是你的计算机、手机或应用程序与外部资源之间的桥梁。

换句话说，API赋予你的软件与其他软件程序、数据库或资源互动的能力。与其为你的应用程序的某一特定功能编写程序，你可以使用具有类似功能的现成的API。

许多API是公共的（免费的），而其他的则是私有的，需要付费购买一个让你访问API的私钥。有不同类型的API，如REST（Representational State Transfer）、SOAP（Simple Object Access Protocol）以及其他。

那么什么是API文档？嗯，它是一个书面指南，说明API的功能、如何将其整合到你的程序中以及API的使用案例，同时还有例子。

请记住，API文档是技术内容。这意味着它将包含一些技术术语，但仍然应该是可读的和容易理解的。

API文档由谁编写？

API是由软件开发人员编写的。由于软件开发人员直接参与了API的建设和使用，所以他们更容易创建文档。

软件开发人员编写API文档的缺点是，他们从一个非常技术性的角度来写，这可能使文档相当难以理解。另一个问题是，API开发者在开发API的同时，还要花费更多的时间来创建文档。

因此，一个好的选择是将API文档的任务分配给技术作家。技术作家是将内容写作和技术知识的专业知识结合起来的人，他制作的文档不仅是技术性的，而且是信息丰富的、可以理解的。

技术文档写作者从API开发者那里了解API，然后创建教程、例子和其他内容，用于编写文档。

同时，API开发者给技术文档写作者提供意见，以确保书面文档的准确性，必要时他们可以向写作者提供更多信息。

我们的目标是让每个人一起工作，制作出能够充分解释API并引导用户的文档，而不至于出现混乱。

如果你对编写API的文档感兴趣，但不知道从哪里开始，也不知道如何开始，这篇文章将帮助你开始。

我可以从这里感受到你的兴奋，所以让我们开始行动吧！

如何开始编写API文档

在编写API文档时，首先要创建几个大纲。这将使你对你打算写的东西有一个概述。

接下来就是为你创建的每个大纲收集信息。这可以通过从API开发者那里获得API描述、使用的语言、其他参考资料和样本案例来实现。你也可以查看API的在线演示，这样你就有了关于它如何工作的第一手经验。

最后，把你收集到的细节结合起来，按逻辑顺序排列。

记得校对你的文件，并在公开前与API开发者分享，以便进行任何修正或补充。

现在你知道从哪里开始，你如何把这些零碎的东西放在一起，使它们成为一个有意义的整体？

API文档中应包括哪些内容

1. 概述

这类似于项目报告的摘要页。

概述应该包含API的摘要和它所解决的问题。它还可以包括使用这个特定API比其他类似API的好处。

2. 教程

这是文档的主要部分。

它应该包括你所使用的不同的内容格式，向用户解释API的概念。它还可以包括供参考的链接，以及整合API和使用它的步骤指南，以便它能正常运作。

3. 例子

当你解释了API的工作原理和/或提供了分项步骤，展示调用、响应、错误处理和其他与开发者如何与API互动有关的操作的例子是个好主意。

4. 词汇表

虽然这是可选的，但我建议为你的API文档添加一个词汇表页面。

为了避免用户被冗长的文本块所烦扰，你在整个文档中使用的各种术语、模式、图像等的解释都可以集中到词汇表中。然后你可以在文档中引用这些东西，并链接到词汇表。

如何编写有用的API文档

了解 API

正如我们刚才所讨论的，你应该对你所记录的API有第一手的知识。记住，你的目标是引导那些可能对API没有任何了解的潜在用户。你不会想让他们感到困惑，对吗？

如果你对产品的架构、功能和其他重要信息有扎实的了解，你就能有效地编写API的产品描述部分，而不需要做任何猜测。

如果你对你要写的API没有充分的了解，那就花点时间做研究，尽可能多地收集信息。自己使用该API，这样你就能对它的工作原理有重要的了解。

使用相关的内容

API文档不只限于书面指南。你可以使用简短的视频或PPT幻灯片来说明API的整合情况。

在写文档的时候说明不同的用例。这将有助于读者认识到哪一个与他们的相似，或者找到一个他们可以很容易联系到的。

另外，在你认为有必要的地方和时候，包括一些代码片段。这将使读者有可能在阅读文档时跟着走。就像那句流行语说的，“告诉我，我会忘记。教我，我就会记住。让我参与，我就会学习”。

要清楚，即使你需要技术性的

API是软件或硬件的指南，所以你在写文档时需要使用一些技术术语。如果你想成为一名技术作家，请抵制含糊其辞。

一份好的文件不是有复杂的语法结构，而是友好的、直接的、清晰的。只有用简单易懂的语言来写，才会有亲和力。

你的API文档应该以最简单的形式出现，但它不应该遗漏任何重要的细节。另外，确保你在第一次使用缩略语和技术术语时对其进行解释，或在文档的最后将其放在词汇表中。

指南分项说明

如果内容被逐项列出，文件就更容易理解。这是写得简洁的一个主要原因。

对指南的步骤进行编号或分项，有助于用户弄清楚在每个时间点上应该做什么。这类似于从A到Z阅读字母表。

有了明确的步骤，用户在遇到错误时可以很容易地找到方向。

检查错误

当你阅读一份文件时，总会有一些东西需要修改、更新，甚至删除。这是作家们的都要经历过，它不应该让你感到不安。

黄金在精炼出来之前要经过几个火热的熔炉。让我们说，你的文件应该经历一个类似的过程（虽然不是火炉），所以它出来时是一个精心准备的文件。

一个彻底的检查过程可以帮助你尽量减少任何错误并产生清晰的文件。

API文档的最佳工具

编写API文档可能相当耗费时间，而且难以维护。但是一个好的文档工具可以缓解大部分，甚至是所有的问题。

现在有许多工具可以让你的API文档之旅变得更容易。使用工具的好处是这些工具提供的协作功能和标准模板，而不是从头开始。

下面是一些流行的工具及其优点的清单。

Postman

Postman是一个用于构建和维护API的平台，具有创建API文档的功能。

Postman使用其机器可读的文档工具，使API文档过程更容易和更快。你可以免费注册Postman并将其安装在你的PC上。

尽管Postman对其制作的所有API文档自动提供更新，但其用户界面一开始可能难以理解。

DapperDox

DapperDox 是一个开源的API文档工具，提供各种主题来创建你的文档。这个工具结合了图表、规范和其他内容类型，为你提供更好的文档。

它的优点是允许作者用 GitHub 风格的 markdown 编写，但这个工具的更新是不定期的。

SwaggerHub

SwaggerHub 是在许多技术作者中一个流行的API文档工具，因为它是互动的，易于使用。

虽然它对初学者很友好，但除了个人使用外，它需要付费。因此，如果你是一个组织的一部分，想使用SwaggerHub，你的组织将不得不为它付费。

无论你是选择这里列出的工具还是选择其他工具，你都应该考虑以下几点：

• 你将在什么环境下使用该工具？是用于个人使用还是作为组织的一部分？
• 你的技术水平如何？你是初学者还是专家？
• 用户界面和用户体验如何？

一些值得学习的API文档的例子

下面是一些API文档，它们给你开始编写优秀的API文档的灵感。这些文件中的每一个都以简单的步骤和可理解的术语向开发者详细介绍了产品API的用法。

GitHub API Docs

GitHub提供了非常有用的文档。在这里查看他们的API文档：

GitHub API Docs

REST API是开发人员用来访问网络或数据库数据的常用API。Github的这个文档包括概述、指南，甚至是如何在你的程序中使用REST API的代码。

这些文档的有趣之处在于，无论你的技术水平如何，你都可以轻松地理解它。

Paystack API Docs

Paystack API Docs

你是否正在构建一个需要支付的应用程序？Paystack是一个用于支付的金融技术解决方案。他们的团队为开发者提供详细的信息，说明如何在你的程序中使用Paystack的API。这更像是提供一本关于使用API的手册，以避免在将API消耗到你的程序中时出现混乱。

Twitter API Docs

推特API文档

Twitter的API文档解释了开发者如何与App互动。这些文件清楚地详述了不同的部分（用户、推文、直接信息等）和它们的操作。

虽然更多的信息需要权限访问，但你只需点击一下链接，就可以访问基本的信息。

结语

文档阐述了一个工具是如何工作的，以便其他人能够正确使用它。创建API文档并不容易，但创建有用的文档并不像你想象的那么难。

只要记住：从写你的初稿开始，每天改进它，当你遇到困难时，向导师或资深同事寻求帮助。

现在就去写那些将与下一个世界级产品一起使用的API文档吧。

前言

首先，WebGL并不是一门语言，它是一个标准，它是在OpenGL ES的基础上所建立的一套适用于浏览器的图形学标准；而OpenGL ES则是OpenGL的一个特殊版本（套娃警告 ），ES版本被广泛的应用于手机、家用游戏机等设备。想了解更多关于WebGL标准内容的小伙伴可以进入Khronos Group的网站自行浏览。

WebGL的开发与我们普通的前端开发并没有什么太大差异，一个浏览器的网页一般是由：HTML、 JavaScript、渲染引擎等部分组成，如果我们要开发WebGL的话，还需要什么呢？让我们来思考一下，我们在高中学习几何的时候老师讲过“点动成线，线动成面，面动成体”，那我们就以最基础的点为例，首先点有什么属性么？在屏幕中的位置、点的颜色、点的大小，我们如何定义一个点的这些属性呢？这就要引入GLSL ES(OpenGL Shader Language ES)（后称着色器）了，着色器的写法与C语言语法有些相似，从名字也能看出WebGL与OpenGL ES是有“血缘关系”的！其次，我们还需要的就是浏览器厂商基于WebGL标准提供的API。

WebGL并不像OpenGL一样有繁琐的环境配置的流程，也没有对系统的要求，只要有一个支持WebGL的浏览器即可！

本次我们使用字符串的形式编写着色器，暂时不新建单独的着色器文件​​

给这个“点”一点自由的空间

为了使用浏览器提供的WebGL接口，我们需要使用<canvas>来获取WebGL上下文：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Point</title>
</head>
<body onload="main()" style="padding: 0; margin: 0;">
  <canvas id="webgl" width="600" height="400">
    您使用的浏览器不支持 WebGL！
  </canvas>
  <script>
    function main() {
      // get canvas element
      const canvas = document.getElementById("webgl");
      const gl = canvas.getContext('webgl');
    }
  </script>
</body>
</html>

gl就是我们所获取到的WebGL渲染的上下文 让我们给画布填充个背景色吧：

<!DOCTYPE html>
<html lang="en">
  <!-- ... -->
  <script>
    function main() {
      // ...
      const gl = canvas.getContext('webgl');
      
      gl.clearColor(0.0, 0.0, 0.0, 1.0);
      gl.clear(gl.COLOR_BUFFER_BIT);
    }
  </script>
  <!-- ... -->
</html>

这样我们要绘制点的画布就拥有了浩瀚宇宙一般深邃的黑色:) 喝点庆祝一下

解释一下gl.clearColor方法是设置清除画布的背景色，形式是RGBA；gl.clear则是调用清除画布的方法，可传递的参数gl.COLOR_BUFFER_BIT是个什么呢 其实该方法继承自OpenGL，OpenGL是基于多缓冲区模型的，清空绘图区域实际上是在清空颜色缓冲区，传递参数gl.COLOR_BUFFER_BIT是在告诉WebGL清空颜色缓冲区；除此之外还有深度缓冲区以及模板缓冲区，可查看此了解。

让距离近一“点”

下面我们开始绘制点 在前面我们分析道一个点有位置、颜色及大小三个属性，下面我们将编写着色器给深邃的画布增添一点色彩

<!DOCTYPE html>
<html lang="en">
  <!-- ... -->
  <script>
    function main() {
      // ...
      const VertexShader = `
        void main() {
          gl_Position = vec4(0.0, 0.0, 0.0, 1.0);
          gl_PointSize = 10.0;
        }
      `;
      const FragmentShader = `
        void main() {
          gl_FragColor = vec4(0.0, 0.0, 1.0, 1.0);
        }
      `;
    }
  </script>
  <!-- ... -->
</html>

上面我们定义了VertexShader和FragmentShader，在WebGL中有两种着色器分别是：顶点着色器和片元着色器：

• 顶点着色器：用来描述顶点的特性的程序，比如位置、大小等。顶点是指二维或三维空间中的一个点，比如二维图形或三维图形的顶点或交点；
• 片元着色器：也称像素着色器，进行逐片的处理过程比如光照。片元可以理解为像素。

同时，每个着色器都有一个main()方法，并且该方法不能指定参数，每行语句结束之后必须有分号！！！ gl_Position、gl_PointSize和gl_FragColor三个变量则是着色器内置的变量，其中gl_PointSize可以不赋值，默认值为1.0。各位注意到，上面赋值语句中我们给的值是0.0而不是0，这是因为这些内置变量是有其变量类型的：

问：明明一个点的坐标只有(x, y, z)，为什么要传4个值呢？
答：这里使用的是齐次坐标的形式，了解齐次坐标可查看我上篇文章《客官，进来看看图形的几何变换？》。
问：使用上面定义的顶点着色器和片元着色器分几步呢？
答：分三步！第一步，创建着色器；第二步，创建着色器程序；第三步，在WebGL上下文中使用着色器程序。

1️⃣创建着色器

为了方便使用我把创建着色器的步骤抽取了一个createShader()方法：

function createShader (gl, type, source) {
  const shader = gl.createShader(type);
  if (shader == null) {
    console.warn('无法创建着色器');
    return null;
  }
​
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
​
  const compiled = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
  if (!compiled) {
    console.log('编译着色器失败： ' + gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  }
​
  return shader;
}

gl.shaderSource是将gl.createShader创建的着色器的source设置为我们定义的VertextShader或FragmentShader，剩下的就不解释了，函数名都很表意:)

2️⃣创建着色器程序

也为了更简洁，创建着色器程序的步骤也抽成了createProgram()方法：

function createProgram (gl, vshader, fshader) {
  const vertexShader = createShader(gl, gl.VERTEX_SHADER, vshader);
  const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fshader);
  if (!vertexShader || !fragmentShader) {
    return null;
  }
​
  const program = gl.createProgram();
  if (!program) {
    return null;
  }
​
  gl.attachShader(program, vertexShader);
  gl.attachShader(program, fragmentShader);
​
  gl.linkProgram(program);
​
  const linked = gl.getProgramParameter(program, gl.LINK_STATUS);
  if (!linked) {
    console.warn('Link 着色器程序失败： ' + gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    gl.deleteShader(fragmentShader);
    gl.deleteShader(vertexShader);
    return null;
  }
  return program;
}

gl.attachShader是将创建好的着色器attach到我们着色器程序上，然后调用gl.linkProgram方法将program整合起来。

3️⃣在上下文中使用着色器程序

function initShaders(gl, vshader, fshader) {
  const program = createProgram(gl, vshader, fshader);
  if (!program) {
    console.warn('创建着色器程序失败！');
    return false;
  }
​
  gl.useProgram(program);
  gl.program = program;
​
  return true;
}

这里就很简单啦，就不做过多介绍了！然后在main()中调用此方法初始化着色器：

<!DOCTYPE html>
<html lang="en">
  <!-- ... -->
  <script>
    function main() {
      const canvas = document.getElementById('webgl');
      const gl = canvas.getContext('webgl');
​
      if (!initShaders(gl, VertexShader, FragmentShader)) {
        return alert('初始化着色器失败');
      }
​
      gl.clearColor(0.0, 0.0, 0.0, 1.0);
      gl.clear(gl.COLOR_BUFFER_BIT);
      gl.drawArrays(gl.POINTS, 0, 1);
    }
    // createShader
    // createProgram
    // initShaders
  </script>
  <!-- ... -->
</html>

gl.drawArrays的第一个参数是指定绘制方式，第二个参数是从哪个顶点开始绘制，第三个参数是指定绘制要用到多少个顶点。这样我们就能在黑色的画布上的正中心看到一个蓝色的点：

但是，小朋友你是否有很多的问号？

明明定义的点的位置在(0, 0, 0)，为什么点会出现在<canvas>的正中央呢？WebGL相对于<canvas>的位置如下图：

中间的是WebGL相对于<canvas>的坐标，而canvas的坐标则是相对于屏幕的！WebGL相对于<canvas>的坐标并不是绝对的像素值，而是相对的[-1.0, 1.0]。 举个例子：我们展示的点在canvas的正中央，如果我们把点的坐标设置为(1.0, 0.0, 0.0, 1.0)，那么点就会出现在canvas的最右侧，同理设置为(-1.0, 1.0, 0.0, 1.0)，点则展示在canvas的左上角:P

渲染这个点经历了什么？

就这么结束了？

怎么可能就这么结束！让我们给绘制点的程序升级一下，现在我们的位置、大小都是在着色器中定义好的。当然WebGL也为我们提供了方法让我们可以从外部传入相应参数值。让我们对着色器改造一下：

const VertexShader = `
  attribute vec4 a_Position;
  void main() {
    gl_Position = a_Position;
    gl_PointSize = 10.0;
  }
`;

attribute是一种GLSL SE变量，被用来从外部向顶点着色器内传数据，只有顶点着色器可以使用；同时还有一种变量类型uniform，uniform变量传输的是对于所有顶点都相同（或与顶点无关）的数据。上面是着色器代码中，我们将从外部获取到的a_Position和a_PointSize分别赋值给gl_Position和gl_PointSize。怎么通过JavaScript向着色器的attribute变量传值呢？

function main () {
  // ...
  if (!initShaders(gl, VertexShader, FragmentShader)) {
    return alert('初始化着色器失败');
  }
​
  const a_Position = gl.getAttribLocation(gl.program, 'a_Position');
  gl.vertexAttrib3f(a_Position, 1.0, 0.0, 0.0);
  // ...
}

使用vertextAttrib3f方法就可以将使用getAttribLocation获取到的attribute变量赋值，vertexAttrib3f方法会将齐次坐标的最后一个值默认赋值为1.0，当然使用vertexAttrib4f也是可以的:)

再加点功能

当我在canvas上点击的时候，就在点击canvas的地方展示一个点，这就需要我们给canvas绑定方法了：

canvas.onmousedown = function (e) {
  click(e, gl, canvas, a_Position);
};

在此就不给详细代码了，canvas绑定事件方式如上，并简单说一下思路：当点击之后获取鼠标在canvas点击的坐标值；然后将坐标转换为WebGL相对于canvas的[-1.0, 1.0]形式的坐标；然后清空画布，在重新绘制点。坐标转换的代码如下：

let x = e.clientX;
let y = e.clientY;
const rect = e.target.getBoundingClientRect();
​
x = (x - rect.left - canvas.width / 2) / (canvas.width / 2);
y = (canvas.height / 2 - y + rect.top) / (canvas.height / 2);

比如还能再给每个点设置不同的颜色，提示：使用 uniform 变量。

结束语

使用原生WebGL绘制一个“简单的点”就讲到这里啦:)我自己也在不断的学习中，后续会出更多关于WebGL的文章。

因为开发过大大大大大大量的 Restful API ，越来越厌烦那种一成不变的代码组织方式。

以 egg为例，要增加一个接口，需要经历繁琐的操作

[路由里注册] ---> [编写 controller] ---> [编写 service] 

哪怕我只是想实现一个 a+b => c！

除此以外，我还调研过某几个比较大的 函数计算 服务商，看看有没有什么好的途径，可以更简便地进行简单接口开发。

让人很失望，天下技术一大抄，它们无一例外都是这样的开发模型：

function(event, context, callback) {}
或者
function(event, context) {}

于是你不得不这样写你的代码

// 举例
function(event, context, callback) {
  const { a, b } = event.arguments; 
  callback(a+b);
}

这算个什么鬼函数？！

你必须改变第一直觉，严格按照厂商的要求来写你的代码，并且寄希望于有人站出来要求它们统一event、context这些旁系知识的实现细节。

并且！

你很难进行本地测试！

你要构造奇奇怪怪的对象作为参数。哪怕只是测试两数相加.

OK! 如果你说，稍微学习一下，其实还是可以用的吧。

可以用就是我们的追求吗？要 应然 还是 实然 ？

难倒我们期望的样子，不应该是这样吗？

// 🔥🔥
function (a, b) {
	return a+b;
}

正文开始：

所以，如果我需要实现一个 a+b => c 的接口，

我期望我的代码是这样的：

export default (a: number, b: number): number => {
  return a + b;
}

我期望我的测试是这样的：

describe('sum', () => {
  it('1+1 is 2', () => {
    assert.equal(sum(1,1), 2);
  });
});

十分明显好吗！

它并不受制于具体平台实现；

它并不需要你学习其他旁系知识，只关注你的功能本身；

它方便测试，因为它就是一个不能再普通的函数；

它可复用！

多说无益，直接动手

export default (a: number, b: number): number => {
  return a + b;
}

有过上一篇的基础，我们直奔抽象语法树：

// 由于只有一行代码，结构就简单多了
{
	type: 'ExportDefaultDeclaration',
	declaration: {
		type: 'ArrowFunctionExpression',
		params: [ 下文展开 ],
		body: { 不重要 },
		returnType: { 下文展开 }
	}
}

我们还是从整体上先看一下，上面这个结构充分表达了源代码的意图：

• 这是一个 export default声明 (ExportDefaultDeclaration )
• 声明的内容是一个箭头函数 (ArrowFunctionExpression )

考虑到，我们希望从这一行代码里面，生成提供HTTP服务的基础代码，

那么我们的主要任务就是，从以上有限的信息当中，提取出Restful API需要的基础信息：

• Method
• Path
• 请求参数

🤖 我们一个一个来解决：

1. HTTP Method

   首选是要确定这个接口，最终通过什么 Method对外服务，在这里源代码并不能提供任何有效信息。

   那么我们就默认用 GET 好了

   🔥其他的 Method，会在文末提及

2. Path， 或者叫 URL

   对于一个接口来说，这也是十分关键的信息，这里我们有两种解决方案

   • 使用函数名，如果有的话
   • 使用当前文件名

   我们姑且把 URL 定为 /sum 好了

   🔥 笔者的一个实验性项目里，使用的是文件名

3. 请求参数

   如果说前面两点都是基于约定，或者一些简单的手段，

   那么在请求参数这个环节，我们必须上价值了，要让 ast 发挥作用！

   我们先展开一下上面 ast 里关于函数参数的部分：

   // params 部分
   [
   	{
   		name: 'a',
   		typeAnnotation: { type: 'TSNumberKeyword' }
   	},
   	{
   		name: 'b',
   		typeAnnotation: { type: 'TSNumberKeyword' }
   	},
   ]
   

   好家伙，可以拿到参数名 a 和 b 了

   结合 TSNumberKeyword 信息，我们甚至能笃定这两个参数是数字类型。

   知道类型，就可以做参数校验！

   🔥通过原始函数定义的参数类型生成 http 参数校验逻辑，比起手工编写 Joi 配置要可靠得多。

   等等，还有一个问题没解决

   参数名和参数类型都有了，缺的就是参数位置以及 content-type 。

   约定大法好，根据多年开发总结得出：

   总所周知， GET 请求的参数就放在 queryString 里吧。

   至于 content-type 统一使用 application/json 不接受反驳

齐活了

结合上面收集到的信息，我们可以想象最终的场景是：

• step 1 : 按上面的方式，编写一个不能再普通的函数
• step 2: 使用我们编写好的工具，运行这个函数
• step 3: 可以通过 http://127.0.0.1:3000/sum?a=11&b=22 来访问这个接口，并且得到结果 33

通过这个截图可知，虽然实现细节比较多，但是可行性是没问题的。

并且笔者已经做出了一个实验性项目。

如果对这种模式比较感兴趣，欢迎前来讨论，在这里就不打广告了。

FAQ 环节

• 更多的 HTTP_METHOD 怎么办？总不能都用 GET 吧

  目前我选能用的方案是，如果没有声明，就用一个默认的 GET，

  因为要尽量选一个能覆盖 90% 情况的作为默认值。

  当我需要使用其他 Method ，我的方案是显式指定，比如

  export const method = 'POST';
  
  export default (a: number, b: number): number => {
    return a + b;
  }
  

  这个方案可以使信息更紧凑，同时不影响函数逻辑跑本地单元测试。

• 上面提到的入参参数位置，什么时候在 queryString，什么时候在其他？

  遵从大多数的案例，GET 的情况下使用 queryString， 其他情况下在 body

  当然还有完全自定义的方案，为避广告嫌疑就不展开了，基本原则还是不影响函数核心逻辑和单元测试。

• 上面提到的 入参参数类型 ，有什么应用场景？

  有了这个信息，如果你喜欢 Joi， 应该能很容易生成参数校验的代码了。

  或者有自己想法的话，和我一样，自己实现一套 validator 也不是什么难事。

function Vue(){
 console.log('test vue');
}
function http(){
  console.log('我是调用接口的http');
}
Vue.prototype.$http = http;
var vm = new Vue();
vm.$http()
vm.$http = 1; // 一旦被修改，虽然一般正常情况下不会被修改
vm.$http(); // 再次调用报错

熟悉Object.defineProperty或者说熟悉对象API的人，一般是如下代码写的，则不会出现被修改的问题。

function Vue(){
 console.log('test vue');
};
function http(){
  console.log('我是调用接口的http');
};
Object.defineProperty(Vue.prototype, '$http', {
    get(){
     return http;
    }
});
var vm = new Vue();
vm.$http();
vm.$http = 1; // 这里无法修改
vm.$http(); // 调用正常

vue-router 源码里就是类似这样写的 (opens new window)，this.$router，this.$route无法修改。

// vue-router 源码
Object.defineProperty(Vue.prototype, '$router', {
	get () { return this._routerRoot._router }
})
Object.defineProperty(Vue.prototype, '$route', {
	get () { return this._routerRoot._route }
})

以下是正文~

之前看到【深度长文】JavaScript数组所有API全解密（opens new window）和JavaScript字符串所有API全解密（opens new window）这两篇高质量的文章。发现没写对象API解析（估计是博主觉得简单，就没写）。刚好我看到《JavaScript面向对象编程指南（第2版）》，觉得有必要写（或者说chao）一下，也好熟悉下对象的所有API用法。

创建对象的两种方式：

var o = new Object();
var o = {}; // 推荐

该构造器可以接受任何类型的参数，并且会自动识别参数的类型，并选择更合适的构造器来完成相关操作。比如：

var o = new Object('something');
o.constructor; // ƒ String() { [native code] }
var n = new Object(123);
n.constructor; // ƒ Number() { [native code] }

Object构造器的成员

Object.prototype

该属性是所有对象的原型（包括 Object对象本身），语言中的其他对象正是通过对该属性上添加东西来实现它们之间的继承关系的。所以要小心使用。 比如：

var s = new String('若川');
Object.prototype.custom = 1;
console.log(s.custom); // 1

Object.prototype 的成员

Object.prototype.constructor

该属性指向用来构造该函数对象的构造器，在这里为Object()

Object.prototype.constructor === Object; // true
var o = new Object();
o.constructor === Object; // true

Object.prototype.toString(radix)

该方法返回的是一个用于描述目标对象的字符串。特别地，当目标是一个Number对象时，可以传递一个用于进制数的参数radix，该参数radix，该参数的默认值为10。

var o = {prop:1};
o.toString(); // '[object Object]'
var n = new Number(255);
n.toString(); // '255'
n.toString(16); // 'ff'

Object.prototype.toLocaleString()

该方法的作用与toString()基本相同，只不过它做一些本地化处理。该方法会根据当前对象的不同而被重写，例如Date(),Number(),Array(),它们的值都会以本地化的形式输出。当然，对于包括Object()在内的其他大多数对象来说，该方法与toString()是基本相同的。 在浏览器环境下，可以通过BOM对象Navigator的language属性（在IE中则是userLanguage）来了解当前所使用的语言：

navigator.language; //'en-US'

Object.prototype.valueOf()

该方法返回的是用基本类型所表示的this值，如果它可以用基本类型表示的话。如果Number对象返回的是它的基本数值，而Date对象返回的是一个时间戳（timestamp）。如果无法用基本数据类型表示，该方法会返回this本身。

// Object
var o = {};
typeof o.valueOf(); // 'object'
o.valueOf() === o; // true
// Number
var n = new Number(101);
typeof n; // 'object'
typeof n.vauleOf; // 'function'
typeof n.valueOf(); // 'number'
n.valueOf() === n; // false
// Date
var d = new Date();
typeof d.valueOf(); // 'number'
d.valueOf(); // 1503146772355

Object.prototype.hasOwnProperty(prop)

该方法仅在目标属性为对象自身属性时返回true,而当该属性是从原型链中继承而来或根本不存在时，返回false。

var o = {prop:1};
o.hasOwnProperty('prop'); // true
o.hasOwnProperty('toString'); // false
o.hasOwnProperty('formString'); // false

Object.prototype.isPrototypeOf(obj)

如果目标对象是当前对象的原型，该方法就会返回true，而且，当前对象所在原型上的所有对象都能通过该测试，并不局限与它的直系关系。

var s = new String('');
Object.prototype.isPrototypeOf(s); // true
String.prototype.isPrototypeOf(s); // true
Array.prototype.isPrototypeOf(s); // false

Object.prototype.propertyIsEnumerable(prop)

如果目标属性能在for in循环中被显示出来，该方法就返回true

var a = [1,2,3];
a.propertyIsEnumerable('length'); // false
a.propertyIsEnumerable(0); // true

在ES5中附加的Object属性

在ES3中，除了一些内置属性（如：Math.PI），对象的所有的属性在任何时候都可以被修改、插入、删除。在ES5中，我们可以设置属性是否可以被改变或是被删除——在这之前，它是内置属性的特权。ES5中引入了属性描述符的概念，我们可以通过它对所定义的属性有更大的控制权。这些属性描述符（特性）包括：

value——当试图获取属性时所返回的值。 writable——该属性是否可写。 enumerable——该属性在for in循环中是否会被枚举 configurable——该属性是否可被删除。 set()——该属性的更新操作所调用的函数。 get()——获取属性值时所调用的函数。 另外，数据描述符（其中属性为：enumerable，configurable，value，writable）与存取描述符（其中属性为enumerable，configurable，set()，get()）之间是有互斥关系的。在定义了set()和get()之后，描述符会认为存取操作已被 定义了，其中再定义value和writable会引起错误。 以下是ES3风格的属性定义方式：

var person = {};
person.legs = 2;

以下是等价的ES5通过数据描述符定义属性的方式：

var person = {};
Object.defineProperty(person, 'legs', {
    value: 2,
    writable: true,
    configurable: true,
    enumerable: true
});

其中， 除了value的默认值为undefined以外，其他的默认值都为false。这就意味着，如果想要通过这一方式定义一个可写的属性，必须显示将它们设为true。 或者，我们也可以通过ES5的存储描述符来定义：

var person = {};
Object.defineProperty(person, 'legs', {
    set:function(v) {
        return this.value = v;
    },
    get: function(v) {
        return this.value;
    },
    configurable: true,
    enumerable: true
});
person.legs = 2;

这样一来，多了许多可以用来描述属性的代码，如果想要防止别人篡改我们的属性，就必须要用到它们。此外，也不要忘了浏览器向后兼容ES3方面所做的考虑。例如，跟添加Array.prototype属性不一样，我们不能再旧版的浏览器中使用shim这一特性。 另外，我们还可以（通过定义nonmalleable属性），在具体行为中运用这些描述符：

var person = {};
Object.defineProperty(person, 'heads', {value: 1});
person.heads = 0; // 0
person.heads; // 1  (改不了)
delete person.heads; // false
person.heads // 1 (删不掉)

Object.defineProperty(obj, prop, descriptor) (ES5)

具体用法可参见上文，或者查看MDN。 MDN Object.defineProperty(obj, descriptor)(opens new window)

Vue.js文档：如何追踪变化 (opens new window)把一个普通 JavaScript 对象传给 Vue 实例的 data 选项，Vue 将遍历此对象所有的属性，并使用 Object.defineProperty 把这些属性全部转为 getter/setter。Object.defineProperty 是仅 ES5 支持，且无法 shim 的特性，这也就是为什么 Vue 不支持 IE8 以及更低版本浏览器的原因。

Object.defineProperties(obj, props) (ES5)

该方法的作用与defineProperty()基本相同，只不过它可以用来一次定义多个属性。 比如：

var glass = Object.defineProperties({}, {
    'color': {
        value: 'transparent',
        writable: true
    },
    'fullness': {
        value: 'half',
        writable: false
    }
});
glass.fullness; // 'half'

Object.getPrototypeOf(obj) (ES5)

之前在ES3中，我们往往需要通过Object.prototype.isPrototypeOf()去猜测某个给定的对象的原型是什么，如今在ES5中，我们可以直接询问改对象“你的原型是什么？”

Object.getPrototypeOf([]) === Array.prototype; // true
Object.getPrototypeOf(Array.prototype) === Object.prototype; // true
Object.getPrototypeOf(Object.prototype) === null; // true

Object.create(obj, descr) (ES5)

该方法主要用于创建一个新对象，并为其设置原型，用（上述）属性描述符来定义对象的原型属性。

var parent = {hi: 'Hello'};
var o = Object.create(parent, {
    prop: {
        value: 1
    }
});
o.hi; // 'Hello'
// 获得它的原型
Object.getPrototypeOf(parent) === Object.prototype; // true 说明parent的原型是Object.prototype
Object.getPrototypeOf(o); // {hi: "Hello"} // 说明o的原型是{hi: "Hello"}
o.hasOwnProperty('hi'); // false 说明hi是原型上的
o.hasOwnProperty('prop'); // true 说明prop是原型上的自身上的属性。

现在，我们甚至可以用它来创建一个完全空白的对象，这样的事情在ES3中可是做不到的。

var o = Object.create(null);
typeof o.toString(); // 'undefined'

Object.getOwnPropertyDesciptor(obj, property) (ES5)

该方法可以让我们详细查看一个属性的定义。甚至可以通过它一窥那些内置的，之前不可见的隐藏属性。

Object.getOwnPropertyDescriptor(Object.prototype, 'toString');
// {writable: true, enumerable: false, configurable: true, value: ƒ toString()}

Object.getOwnPropertyNames(obj) (ES5)

该方法返回一个数组，其中包含了当前对象所有属性的名称（字符串），不论它们是否可枚举。当然，也可以用Object.keys()来单独返回可枚举的属性。

Object.getOwnPropertyNames(Object.prototype);
// ["__defineGetter__", "__defineSetter__", "hasOwnProperty", "__lookupGetter__", "__lookupSetter__", "propertyIsEnumerable", "toString", "valueOf", "__proto__", "constructor", "toLocaleString", "isPrototypeOf"]
Object.keys(Object.prototype);
// []
Object.getOwnPropertyNames(Object);
// ["length", "name", "arguments", "caller", "prototype", "assign", "getOwnPropertyDescriptor", "getOwnPropertyDescriptors", "getOwnPropertyNames", "getOwnPropertySymbols", "is", "preventExtensions", "seal", "create", "defineProperties", "defineProperty", "freeze", "getPrototypeOf", "setPrototypeOf", "isExtensible", "isFrozen", "isSealed", "keys", "entries", "values"]
Object.keys(Object);
// []

Object.preventExtensions(obj) (ES5)

Object.isExtensible(obj) (ES5)

preventExtensions()方法用于禁止向某一对象添加更多属性，而isExtensible()方法则用于检查某对象是否还可以被添加属性。

var deadline = {};
Object.isExtensible(deadline); // true
deadline.date = 'yesterday'; // 'yesterday'
Object.preventExtensions(deadline);
Object.isExtensible(deadline); // false
deadline.date = 'today';
deadline.date; // 'today'
// 尽管向某个不可扩展的对象中添加属性不算是一个错误操作，但它没有任何作用。
deadline.report = true;
deadline.report; // undefined

Object.seal(obj) (ES5)

Object.isSeal(obj) (ES5)

seal()方法可以让一个对象密封，并返回被密封后的对象。 seal()方法的作用与preventExtensions()基本相同，但除此之外，它还会将现有属性 设置成不可配置。也就是说，在这种情况下，我们只能变更现有属性的值，但不能删除或（用defineProperty()）重新配置这些属性，例如不能将一个可枚举的属性改成不可枚举。

var person = {legs:2};
// person === Object.seal(person); // true
Object.isSealed(person); // true
Object.getOwnPropertyDescriptor(person, 'legs');
// {value: 2, writable: true, enumerable: true, configurable: false}
delete person.legs; // false (不可删除，不可配置)
Object.defineProperty(person, 'legs',{value:2});
person.legs; // 2
person.legs = 1;
person.legs; // 1 (可写)
Object.defineProperty(person, "legs", { get: function() { return "legs"; } });
// 抛出TypeError异常

Object.freeze(obj) (ES5)

Object.isFrozen(obj) (ES5)

freeze()方法用于执行一切不受seal()方法限制的属性值变更。Object.freeze() 方法可以冻结一个对象，冻结指的是不能向这个对象添加新的属性，不能修改其已有属性的值，不能删除已有属性，以及不能修改该对象已有属性的可枚举性、可配置性、可写性。也就是说，这个对象永远是不可变的。该方法返回被冻结的对象。

var deadline = Object.freeze({date: 'yesterday'});
deadline.date = 'tomorrow';
deadline.excuse = 'lame';
deadline.date; // 'yesterday'
deadline.excuse; // undefined
Object.isSealed(deadline); // true;
Object.isFrozen(deadline); // true
Object.getOwnPropertyDescriptor(deadline, 'date');
// {value: "yesterday", writable: false, enumerable: true, configurable: false} (不可配置，不可写)
Object.keys(deadline); // ['date'] (可枚举)

Object.keys(obj) (ES5)

该方法是一种特殊的for-in循环。它只返回当前对象的属性（不像for-in），而且这些属性也必须是可枚举的（这点和Object.getOwnPropertyNames()不同，不论是否可以枚举）。返回值是一个字符串数组。

Object.prototype.customProto = 101;
Object.getOwnPropertyNames(Object.prototype);
// [..., "constructor", "toLocaleString", "isPrototypeOf", "customProto"]
Object.keys(Object.prototype); // ['customProto']
var o = {own: 202};
o.customProto; // 101
Object.keys(o); // ['own']

四、在ES6中附加的Object属性

Object.is(value1, value2) (ES6)

该方法用来比较两个值是否严格相等。它与严格比较运算符（===）的行为基本一致。 不同之处只有两个：一是+0不等于-0，而是NaN等于自身。

Object.is('若川', '若川'); // true
Object.is({},{}); // false
Object.is(+0, -0); // false
+0 === -0; // true
Object.is(NaN, NaN); // true
NaN === NaN; // false

ES5可以通过以下代码部署Object.is

Object.defineProperty(Object, 'is', {
    value: function() {x, y} {
        if (x === y) {
           // 针对+0不等于-0的情况
           return x !== 0 || 1 / x === 1 / y;
        }
        // 针对 NaN的情况
        return x !== x && y !== y;
    },
    configurable: true,
    enumerable: false,
    writable: true
});

Object.assign(target, ...sources) (ES6)

该方法用来源对象（source）的所有可枚举的属性复制到目标对象（target）。它至少需要两个对象作为参数，第一个参数是目标对象target，后面的参数都是源对象（source）。只有一个参数不是对象，就会抛出TypeError错误。

var target = {a: 1};
var source1 = {b: 2};
var source2 = {c: 3};
obj = Object.assign(target, source1, source2);
target; // {a:1,b:2,c:3}
obj; // {a:1,b:2,c:3}
target === obj; // true
// 如果目标对象与源对象有同名属性，或多个源对象有同名属性，则后面的属性会覆盖前面的属性。
var source3 = {a:2,b:3,c:4};
Object.assign(target, source3);
target; // {a:2,b:3,c:4}

Object.assign只复制自身属性，不可枚举的属性（enumerable为false）和继承的属性不会被复制。

Object.assign({b: 'c'},
    Object.defineProperty({}, 'invisible', {
        enumerable: false,
        value: 'hello'
    })
);
// {b: 'c'}

属性名为Symbol值的属性，也会被Object.assign()复制。

Object.assign({a: 'b'}, {[Symbol('c')]: 'd'});
// {a: 'b', Symbol(c): 'd'}

对于嵌套的对象，Object.assign()的处理方法是替换，而不是添加。

Object.assign({a: {b:'c',d:'e'}}, {a:{b:'hello'}});
// {a: {b:'hello'}}

对于数组，Object.assign()把数组视为属性名为0、1、2的对象。

Object.assign([1,2,3], [4,5]);
// [4,5,3]

Object.getOwnPropertySymbols(obj) (ES6)

该方法会返回一个数组，该数组包含了指定对象自身的（非继承的）所有 symbol 属性键。 该方法和 Object.getOwnPropertyNames() 类似，但后者返回的结果只会包含字符串类型的属性键，也就是传统的属性名。

Object.getOwnPropertySymbols({a: 'b', [Symbol('c')]: 'd'});
// [Symbol(c)]

Object.setPrototypeOf(obj, prototype) (ES6)

该方法设置一个指定的对象的原型 ( 即, 内部[[Prototype]]属性）到另一个对象或 null。 __proto__属性用来读取或设置当前对象的prototype对象。目前，所有浏览器（包括IE11）都部署了这个属性。

// ES6写法
var obj = {
    method: function(){
        // code ...
    }
};
// obj.__proto__ = someOtherObj;
// ES5写法
var obj = Object.create(someOtherObj);
obj.method = function(){
    // code ...
};

该属性没有写入ES6的正文，而是写入了附录。__proto__前后的双下划线说明它本质上是一个内部属性，而不是正式对外的一个API。无论从语义的角度，还是从兼容性的角度，都不要使用这个属性。而是使用Object.setPrototypeOf()（写操作），Object.getPrototypeOf()（读操作），或Object.create()（生成操作）代替。 在实现上，__proto__调用的Object.prototype.__proto__。 Object.setPrototypeOf()方法的作用与__proto__作用相同，用于设置一个对象的prototype对象。它是ES6正式推荐的设置原型对象的方法。

在ES8中附加的Object属性

Object.getOwnPropertyDescriptors(obj) (ES8)

该方法基本与Object.getOwnPropertyDescriptor(obj, property)用法一致，只不过它可以用来获取一个对象的所有自身属性的描述符。

Object.getOwnPropertyDescriptor(Object.prototype, 'toString');
// {writable: true, enumerable: false, configurable: true, value: ƒ toString()}
Object.getOwnPropertyDescriptors(Object.prototype); // 可以自行在浏览器控制台查看效果。

Object.values(obj) (ES8)

Object.values() 方法与Object.keys类似。返回一个给定对象自己的所有可枚举属性值的数组，值的顺序与使用for...in循环的顺序相同 ( 区别在于for-in循环枚举原型链中的属性 )。

var obj = {a:1,b:2,c:3};
Object.keys(obj); // ['a','b','c']
Object.values(obj); // [1,2,3]

Object.entries(obj) (ES8)

Object.entries() 方法返回一个给定对象自己的可枚举属性[key，value]对的数组，数组中键值对的排列顺序和使用 for...in 循环遍历该对象时返回的顺序一致（区别在于一个for-in循环也枚举原型链中的属性）。

var obj = {a:1,b:2,c:3};
Object.keys(obj); // ['a','b','c']
Object.values(obj); // [1,2,3]
Object.entries(obj); // [['a',1],['b',2],['c',3]]

六、在ES10中附加的Object属性

Object.fromEntries(iterable) (ES10)

Object.fromEntries()方法返回一个给定可迭代对象（类似Array、Map或其他可迭代对象）对应属性的新对象。

Object.fromEntries() 是 Object.entries()的逆操作。

var arr = [['a',1],['b',2],['c',3]];
Object.fromEntries(obj); // {a: 1, b: 2, c: 3}
var entries = new Map([
  ['name', '若川'],
  ['age', 18]
]);
Object.fromEntries(entries) // {name: '若川', age: 18}

小结

细心的读者可能会发现MDN上还有一些API，本文没有列举到。因为那些是非标准的API。熟悉对象的API对理解原型和原型链相关知识会有一定帮助。常用的API主要有Object.prototype.toString()，Object.prototype.hasOwnProperty()， Object.getPrototypeOf(obj)，Object.create()，Object.defineProperty，Object.keys(obj)，Object.assign()。

参考资料

MDN Object API(opens new window)
JavaScript面向对象编程指南（第2版）（豆瓣读书链接）(opens new window)
阮一峰 ES6标准入门2(opens new window)

欢迎阅读我的更多文章。

这个入门教程会带着你一起构建一个 RESTful API，我会解释一些术语，并使用 NodeJS 来编码实现一个服务端程序。

术语解释

REST 是什么？维基百科：

表现层状态转换（Representational state transfer，REST） 是一种软件架构风格，它定义了一组创建 Web 服务的约束。RESTful Web 服务允许请求系统通过使用统一和预定义的无状态操作集来访问和操作 Web 资源的文本表示。

揭开神秘面纱，看看 REST 究竟是什么意思。REST 基本上就是客户端和服务端通信的一组规则。REST 架构的限制条件：

1. 客户端-服务器架构：网站/应用的用户界面与数据请求/存储应当是分离的，两者可以独立扩展。
2. 无状态：通讯过程中服务端不会保存客户端的上下文信息，意味着每个请求都需要携带必要的数据、不能指望服务器会使用之前的请求中携带的数据。
3. 分层系统：客户端不应该了解它是与服务器直接通讯还是与一些中介服务进行通讯，中介服务（代理或负载均衡）为底层服务器的扩展性和安全性提供了保障。

理解了 RESTful 服务之后，再了解一下标题中提到的一些术语：

1. REST 客户端：访问 REST 服务的代码或应用。你现在正在用着它呢！浏览器可以看做是一个不受我们控制的 REST 客户端（我们访问的网站会处理浏览器的请求）。在很长一段时间内，浏览器都是使用内建的 XMLHttpRequest 函数来发起 REST 请求，不过现在它被现代的、基于 promise 的 FetchAPI 替代了。其他 REST 客户端还包括：axios、superagent、got 等代码库，Postman（或其在线版本 postwoman）等专用应用，以及 cURL 等命令行工具。
2. REST 服务：服务器。有许多流行的库能帮助我们轻松创建 REST 服务，如 NodeJS 环境下的 ExpressJS 和 Python 环境下的 Django。
3. REST API：定义了从服务器存取数据的端点和方法，稍后会详细介绍。其它替代方案包括：GraphQL、JSON-Pure 以及 oData。

现在告诉我，REST 是什么？

广义地说，就是客户端向服务端请求访问指定数据或者在服务端保存数据、服务端响应客户端请求的过程。

从编程角度来说，服务端提供了一个端点（URL）等待接收客户端的请求，客户端连接这个端点并发送数据（记住，REST 是无状态的，请求中携带的数据不会被存储）、服务端返回正确的响应。

文字是枯燥的，我们来看看示例。使用 Postman 来展示请求和响应：

配置 postman 请求

返回的数据是 JSON（JavaScript Object Notation）格式的，可以直接访问。

这里的 https://official-joke-api.appspot.com/random_joke 被称为 API 端点，服务端会监听指向这个端点的请求。

REST 剖析：

现在我们知道了客户端可以向服务端发送携带数据的请求、服务端会返回适当的响应，再来深入了解一下如何构造一个请求。

1. 端点（Endpoint）：前面已经介绍过了，这里再复习一下：它是 REST 服务器监听的 URL 地址。

2. 请求方法（Method）：之前有介绍到，你可以从服务器获取数据或者修改数据，那么服务器怎么知道客户端想要做什么操作呢？REST 为不同的请求类型实现了许多“方法”，以下是最常用的：

   - GET：从服务器获取资源。

   - POST：在服务器上保存资源。

   - PATCH 或 PUT：更新服务器上的现有资源。

   - DELETE：删除服务器上现有的资源。

3. 头部信息（Headers）：用于客户端和服务端通讯的额外信息（记住，REST 是无状态的）。常见的头部信息如下：

   请求头（Request）：

   - host：客户端的 IP 地址（或请求的源地址）

   - accept-language：客户端接受的语言类型

   - user-agent：客户端的详细信息，如操作系统和浏览器类型

   响应头（Response）：

   - status：请求的状态或 HTTP 状态码

   - content-type：服务器返回的资源的类型

   - set-cookie：服务器设置的 cookies

4. 请求数据（Data）：（也称为请求体或消息）包含了将要发送给服务器的数据

跳出细节 - 开始编码

在 Node 环境中编写 REST 服务的代码，我们会实现上面学到的全部内容。在编码过程中会用到 ES6+ 的语法。

要确保你已经安装了 Node.JS，并且 node 和 npm 命令是可用的，我自己使用的版本分别是 Node 12.16.2 和 NPM 6.14.4。

创建一个名为 rest-service-node 的文件夹，并使用 cd 命令进入：

mkdir rest-service-node
cd rest-service-node

初始化 node 项目：

npm init -y

参数 -y 表示跳过所有配置项。如果想要手动填写这些配置的话，执行 npm init。

安装一些依赖包，这里使用 ExpressJS 框架来开发 REST 服务。执行以下命令来安装：

npm install --save express body-parser

这里的 body-parser 是做什么用的？默认情况下，Express 是无法处理 POST 请求传入的 JSON 数据的，body-parser 为 Express 解决了这个问题。

创建 server.js 文件，写入以下代码：

const express = require("express");
const bodyParser = require("body-parser");

const app = express();
app.use(bodyParser.json());

app.listen(5000, () => {
  console.log(`Server is running on port 5000.`);
});

前两行代码引入了 Express 和 body-parser。

第三行代码初始化了一个 Express 服务器，并把它赋值给一个名为 app 的变量。

app.use(bodyParser.json()); 初始化了 body-parser 插件。

最后，设置服务器监听 5000 端口的请求。

从 REST 服务器获取数据

使用 GET 请求来获取服务器的数据，在 app.listen 之前插入以下代码：

const sayHi = (req, res) => {
  res.send("Hi!");
};

app.get("/", sayHi);

这里创建了一个 sayHi 函数，它接受 req 和 res 两个参数（稍后会解释）、返回字符串“Hi!”作为响应。

app.get() 方法接受两个参数：接口路径以及有客户端请求这个接口时执行的回调函数。所以最后一行代码可以理解为：服务器监听”/“路径（可能是主页）的请求，如果监听到这个路径上的请求就执行 sayHi 函数。

app.get 还为我们提供了一个包含了客户端发送的所有数据的 request 对象，以及一个包含了所有响应方法的 response 对象。虽然它们是作为函数参数来访问的（随意命名也不影响功能），但是一般命名约定建议将它们命名为 res（表示 response） 和 req（表示 request）。

闲言少叙，启动服务器！执行以下代码：

node server.js

如果一切顺利的话，应该能在控制台看到这个提示：Server is running on port 5000.

提示：可以将端口号改为任意合适的值。

打开浏览器，访问 [http://localhost:5000/][11]，将看到如下内容：

第一个 GET 请求成功执行了！

向 REST 服务器发送数据

接下来构建一个 POST 请求，这个请求向服务器传入两个数字、服务器会计算并返回两数之和。在 app.get 之后加入以下代码：

app.post("/add", (req, res) => {
  const { a, b } = req.body;
  res.send(`The sum is: ${a + b}`);
});

我们以 JSON 格式向服务器发送数据：

{
    "a":5,
    "b":10
}

理解一下代码：

第一行调用了 ExpressJS 的 .post() 方法，使得服务器监听 POST 请求，它接受的参数与 .get() 方法相同。这里指定的接口路径是 /add，这样其他人可以通过你的 IP 地址和端口（[http://your-ip-address:port/add][12]）来访问这个接口，在本地也可以通过 localhost:5000/add 这个地址来访问。这里回调函数是以行内函数的形式来编写的。

第二行使用了 ES6 的对象解构语法来读取对象属性。通过请求发送的数据都被保存在了 req 对象的 body 属性中，实际上也可以用以下代码来读取这两个值：

const num1 = req.body.a;
const num2 = req.body.b;

第三行使用 res 对象的 send() 方法来返回计算结果，这里使用了 ES6 的模板字符串语法。使用 Postman 测试一下：

我们在请求体中设置 a 的值为 5、b 的值为 10，Postman 会在发送的请求中携带这些数据。服务器接收到这个请求时，会以上面的代码所示的方式解析 req.body 中的数据。返回结果展示在下方。

最终代码：

const express = require("express");
const bodyParser = require("body-parser");

const app = express();

app.use(bodyParser.json());

const sayHi = (req, res) => {
  res.send("Hi!");
};

app.get("/", sayHi);

app.post("/add", (req, res) => {
  const { a, b } = req.body;
  res.send(`The sum is: ${a + b}`);
});

app.listen(5000, () => {
  console.log(`Server is running on port 5000.`);
});

REST 客户端

我们已经创建了一个服务端程序，那么要如何在网站或者 web 程序中访问它呢？现在 REST 客户端库就派上用场了。

我们会构建一个 web 应用，它包含一个表格，可以在其中填入两个数字，从服务端获得它们的计算结果后会展示在页面上。

首先，修改 server.js：

const path = require("path");
const express = require("express");
const bodyParser = require("body-parser");
const app = express();
app.use(bodyParser.json());
app.get("/", (req, res) => {
  res.sendFile(path.join(__dirname, "index.html"));
});
app.post("/add", (req, res) => {
  const { a, b } = req.body;
  res.send({
    result: parseInt(a) + parseInt(b)
  });
});

我们引入了 Node 提供的 path 包，用来跨平台地操作路径。接着改变了”/“路径上的 GET 请求的回调函数，在其中使用了 res 对象提供的 sendFile 方法，这个方法允许我们在响应中返回任意格式的文件。所以，每当用户访问”/“路径的时候，他们会看到 index.html 页面的内容。

最后修改了 app.post 函数，现在它会将 a 和 b 转换为整数，并以 JSON 形式返回两者之和。

创建一个名为 index.html 的 html 页面，并在其中添加一些基本样式：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>REST Client</title>
  </head>
  <style>
    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }
    .container {
      height: 100vh;
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
    }
    form {
      display: flex;
      flex-direction: column;
      margin-bottom: 20px;
    }
    label,
    input[type="submit"] {
      margin-top: 20px;
    }
  </style>
  <body>
    <div class="container">
      <h1>Simple POST Form</h1>
      </h1>
      <form>
        <label>Number 1:</label>
        <input id="num1" type="number" />
        <label>Number 2:</label>
        <input id="num2" type="number" />
        <input type="submit" value="Add"/>
      </form>
      <div class="result">Click Add!</div>
    </div>
  </body>
</html>

在闭合 body 标签之前插入一段 JavaScript 脚本，这样我们就不必维护一个独立的 .js 文件了。我们监听 document 的 submit 事件并为其指定一个回调函数：

<script>
    document.addEventListener("submit", sendData);
</script>

首先要避免在点击“Add”按钮时刷新页面，可以使用 preventDefault() 方法来实现，同时要获取两个输入框的值：

function sendData(e) {
    e.preventDefault();
    const a = document.querySelector("#num1").value;
    const b = document.querySelector("#num2").value;
}

使用 a 和 b 的值向服务端发送请求。这里我们使用浏览器内置的 Fetch API 来发送请求。

Fetch 接收两个参数：接口地址和 JSON 形式的请求参数对象，返回一个 Promise。相关知识超出了本文范围，请自行查阅。

在 sendData() 函数中加入以下代码：

fetch("/add", {
        method: "POST",
        headers: {
            Accept: "application/json",
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            a: parseInt(a),
            b: parseInt(b)
        })
    })
    .then(res => res.json())
    .then(data => {
        const {
            result
        } = data;
        document.querySelector(
            ".result"
        ).innerText = `The sum is: ${result}`;
    })
    .catch(err => console.log(err));

把接口地址的相对路径作为 fetch 函数的第一个参数传入，接着传入一个参数对象作为第二个参数，其中指定了请求方式为 POST。

参数对象中还包含了 headers 参数，其中指定了请求中发送的数据的格式（content-type）和预期响应的数据格式（accept）。

接着传入了请求体 body。还记得使用 Postman 时以 JSON 格式输入数据吗？这里也是类似的情况。由于 express 将请求体当做字符串来处理，并根据 content-type 来解析，所以我们需要使用 JSON.stringify() 方法来将请求体转换为字符串。我们格外谨慎地把输入值转换为了整数，以确保这个请求不会破坏服务器（因为我们没有做数据类型校验）。

最后，如果 fetch 返回的 promise 状态变为完成（fullfilled），我们就能获取到响应数据并将其转换为 JSON 格式，然后就可以在响应对象中获取计算结果并将结果展示在页面上。

如果这个 promise 的状态变为拒绝（rejected），则会在控制台打印错误信息。

index.html 的最终代码如下：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>REST Client</title>
  </head>
  <style>
    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }
    .container {
      height: 100vh;
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
    }
    form {
      display: flex;
      flex-direction: column;
      margin-bottom: 20px;
    }
    label,
    input[type="submit"] {
      margin-top: 20px;
    }
  </style>
  <body>
    <div class="container">
      <h1>Simple POST Form</h1>
      </h1>
      <form>
        <label>Number 1:</label>
        <input id="num1" type="number" />
        <label>Number 2:</label>
        <input id="num2" type="number" />
        <input type="submit" value="Add"/>
      </form>
      <div class="result">Click Add!</div>
    </div>
    <script>
      document.addEventListener("submit", sendData);
      function sendData(e) {
        e.preventDefault();
        const a = document.querySelector("#num1").value;
        const b = document.querySelector("#num2").value;

        fetch("/add", {
          method: "POST",
          headers: {
            Accept: "application/json",
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            a: parseInt(a),
            b: parseInt(b)
          })
        })
          .then(res => res.json())
          .then(data => {
            const { result } = data;
            document.querySelector(
              ".result"
            ).innerText = `The sum is: ${result}`;
          })
          .catch(err => console.log(err));
      }
    </script>
  </body>
</html>

我在 glitch 上部署了一个小应用供你测试。

总结：

通过本文，我们学习了 REST 架构和 REST 请求的相关知识，我们一起构建了一个简单的能够处理 GET 和 POST 请求的 REST 服务器，还构建了一个 web 应用作为 REST 客户端来计算两数之和。

你可以扩展这个项目来处理更多其它类型的请求，甚至将它扩展成一个完整的后端应用。

希望本文能对你有所帮助。如果有任何疑问，可以随时在 twitter 上联系我。Happy Coding!

原文：REST API Tutorial – REST Client, REST Service, and API Calls Explained With Code Examples，作者：Vaibhav Kandwal

现在，我经常使用这个术语，以至于我最近尝试在酒吧订购 API。

调酒师的反应是抛出 404：资源未找到。

我遇到了很多在技术领域和其他领域工作的人，他们对这个相当常见的术语的含义理解不太清楚或不正确。

从技术上讲，API 代表应用程序编程接口。在某些时候，大多数大公司已经为其客户或自己内部使用构建了 API。

但是，你如何用简单的语言解释 API？ 还有比在开发和业务中使用的含义更广泛的含义吗？ 首先，让我们回顾一下网络本身的工作方式。

WWW 和远程服务器

当我想到 Web 时，我想到的是连接 服务器 的大型网络。

互联网上的每个页面都存储在远程服务器上的某个位置。远程服务器并不是那么神秘——它只是被优化了以处理请求的远程计算机的一部分。

为了使事情更直观，你可以在笔记本电脑上启动一个服务器，该服务器能够将整个网站服务于 Web（实际上，本地服务器是工程师在向公众发布网站之前用来开发网站的工具）。

当你在浏览器中输入 www.facebook.com 时，请求将发送到 Facebook 的远程服务器。 浏览器收到响应后，将解释代码并显示页面。

对于 浏览器（也称为客户端）而言，Facebook 的服务器是一种 API。这意味着，每次你访问 Web 页面时，你都会与某些远程服务器的 API 进行交互。

API 与远程服务器不同，它是服务器中接收请求和发送响应的部分。

用 API 服务客户

你可能听说过将 API 打包为产品的公司。例如，Weather Underground 出售对其天气数据 API 的访问权。

示例场景：你的小型企业网站上有一个表格，客户用它登录以安排预约。你想让客户能够自动创建带有该预约的详细信息的 Google 日历提醒。

API 的使用：让你的网站的服务器直接与 Google 的服务器通信，并请求创建具有给定详细信息的事件。 然后，你的服务器将收到 Google 的响应，进行处理，然后将相关信息发送回浏览器，例如向用户发送确认消息。

另外，你的浏览器通常可以绕过服务器直接向 Google 服务器直接发送 API 请求。

此 Google 日历的 API 与现有的其他远程服务器的 API 有何不同？

用技术术语来说，区别在于请求和响应的格式。

要呈现整个网页，你的浏览器需要获得 HTML 形式的响应，其中包含演示代码，而 Google 日历的 API 调用只会返回数据（可能采用 JSON 格式）。

如果你的网站的服务器正在发出 API 请求，那么你的网站服务器就是客户端（类似于你使用浏览器浏览到网站时，浏览器就是客户端）。

从用户的角度来看，API 使他们无需离开你的网站即可完成操作。

大多数现代网站至少使用一些第三方 API。

许多问题已经有了第三方解决方案，无论是库还是服务。使用已有的解决方案通常更容易、更可靠。

开发团队将应用程序分解成多个通过 API 相互通信的服务器的情况并不少见。为主应用程序服务器执行辅助功能的服务器通常被称为 微服务。

总而言之，当一家公司向其客户提供 API 时，仅表示他们已经建立了一组专用 URL，这些 URL 返回纯数据响应——这意味着响应将不包含任何你在图形用户界面（如网站）中看到的展示型的内容。

你可以使用浏览器发出这些请求吗？通常情况下，是的。由于实际的 HTTP 传输是以文本形式进行的，因此你的浏览器将始终尽力显示响应。

例如，你可以直接使用浏览器访问 GitHub 的 API，甚至不需要访问令牌。这是在浏览器中访问 GitHub 用户的 API 路由时收到的 JSON 响应（https://api.github.com/users/petrgazarov）：

{  "login": "petrgazarov",  "id": 5581195,  "avatar_url": "https://avatars.githubusercontent.com/u/5581195?v=3",  "gravatar_id": "",  "url": "https://api.github.com/users/petrgazarov",  "html_url": "https://github.com/petrgazarov",  "followers_url": "https://api.github.com/users/petrgazarov/followers",  "following_url": "https://api.github.com/users/petrgazarov/following{/other_user}",  "gists_url": "https://api.github.com/users/petrgazarov/gists{/gist_id}",  "starred_url": "https://api.github.com/users/petrgazarov/starred{/owner}{/repo}",  "subscriptions_url": "https://api.github.com/users/petrgazarov/subscriptions",  "organizations_url": "https://api.github.com/users/petrgazarov/orgs",  "repos_url": "https://api.github.com/users/petrgazarov/repos",  "events_url": "https://api.github.com/users/petrgazarov/events{/privacy}",  "received_events_url": "https://api.github.com/users/petrgazarov/received_events",  "type": "User",  "site_admin": false,  "name": "Petr Gazarov",  "company": "PolicyGenius",  "blog": "http://petrgazarov.com/",  "location": "NYC",  "email": "petrgazarov@gmail.com",  "hireable": null,  "bio": null,  "public_repos": 23,  "public_gists": 0,  "followers": 7,  "following": 14,  "created_at": "2013-10-01T00:33:23Z",  "updated_at": "2016-08-02T05:44:01Z"}

浏览器似乎已经很好地显示了 JSON 响应。这样的 JSON 响应已准备好在你的代码中使用。从此文本中提取数据很容易。然后，你可以对数据进行任何操作。

A 代表 “Application”（应用）

最后，我们再举几个 API 示例。

“应用程序”可以指很多东西。以下是一些与 API 相关的内容：

• 一款功能独特的软件
• 整个服务器，整个应用程序或应用程序的一小部分

基本上，任何可以与环境区别开来的软件都可以是 API 中的 “ A”，并且可能还具有某种 API。

假设你在代码中使用了第三方库，当库被合并到你的代码中，它便成为整个应用程序的一部分。作为一个独立的软件，该库可能会有一个 API，该 API 可以与您的其余代码进行交互。

这是另一个示例：在面向对象设计中，代码被组织为对象。你的应用程序可能定义了数百个可以相互交互的对象。

每个对象都有一个API——一组用于与应用程序中其他对象进行交互的 公共 方法和属性。

对象也可能具有内部逻辑，这是 私有 的，这意味着它对外部作用域（而不是 API）是隐藏的。

希望你通过本文的介绍理解 API 的广泛含义以及当今该术语的更常见用法。

有趣的资源：

一个很棒关于 DNS 的 YouTube 视频

HTTP 协议基础

可汗学院关于“面向对象设计原则”的精彩视频

原文：What is an API? In English, please，作者：Petr Gazarov