@acter/gateway 中文文档教程

Question

Reaction Gateway

带有大量内置工具的企业平台的简单“让我开发”API 网关 立即将您的想法付诸实践！

尽管 Reaction Gateway 处于预发布阶段，但它已经在生产中使用，每天在全球托管数百万个连接。

TL/DR;

阅读安装和入门部分。 此网关已预先配置为开箱即用，但请阅读配置部分以在几秒钟内设置您想要实现的目标，然后您将需要查看服务部分并构建您的第一项服务，也许可以尝试一些预构建的服务，例如 status。

Executive summary

Reaction gateway 是一个强大的 API 网关框架的新开源版本，由 20 年经验丰富的软件架构师和专业的 Node 开发人员构建。 这个网关或其衍生产品为许多大公司（包括康卡斯特、ESPN、迪士尼以及许多医院、律师事务所和初创公司）使用的后端提供支持。

将其发布到社区是因为与我合作的许多公司都想将他们拥有的其他平台转移到网关中，但不知道从哪里开始，而且大多数现有网关的学习曲线都很高。

Reaction Gateway 旨在为您提供构建即时后端所需的工具，以便您可以立即开始开发杀手级应用程序。 然而，它具有足够的活力和远见，还可以为您提供一条清晰的路径，使您的后端达到行星规模甚至更远（您可以坚持使用这个网关，并使用像 Kubernetes)。

如果您当前未使用 API 网关，则需要使用 API 网关。

What's a gateway?

API 网关（就是这样），将开发人员意识到他们需要在现代后端中完成的许多事情集中到一个简洁易用的地方。 他们还在您的平台中提供了一个API，允许您的应用程序使用单一平台组件与任何其他应用程序对话。

由于网关包含模块化可插入组件，因此可以将更多平台组件改编为平台方面。 面向方面编程 (AOP) 及其表亲 mixin 已经在开发者社区中大行其道，留下了更好的设计它所到之处的尾迹。 因此，API 网关将这种思维方式带到平台层或最顶层，它当然属于那里。

API 网关是未来。 如果您不相信我，请相信 Google，它最近以 6.25 亿美元。

一个设计得当的 API 网关可以为您提供整个平台减去您的服务，包括平台的所有额外“方面”，这些通常是经过深思熟虑才附加的，使您的平台更加健壮、安全和稳定。

毕竟，平台是为了支持您的应用程序或想法，而不是扼杀它。 如果您曾经开发过没有 API 网关的平台，您就会注意到您是多么专注于您的平台而不是平台的意图。 这不好。 让网关向您展示您的烦恼如何像一块美味的巧克力一样融化。

Gateway benefits

网关使得创建上帝对象或整体变得非常困难，并且非常容易开发微服务或现代 FaaS/Lambda 服务。 网关成为您进入世界的中心和唯一接口，并通过平台服务传播工作，业界一致认为这是目前已知的最佳设计。

Query agregation

网关还可以承载现代聚合逻辑，如 GraphQL，消除应用程序为加载单个页面而发出 20 次或更多 API 请求所导致的减速（ GraphQL 可以将这 20 个请求转换为一个请求，并且使用水化模式，你可以将其变为零请求）。

Platform features in one place

通过在单个逻辑位置处理缓存、审计、日志记录、安全、黑名单、转换、A/B 测试、ETL 等，网关还大大降低了后端的复杂性。 有没有想过 AWS、GCP 和 Azure 如何持续生产高级和复杂的 SaaS 产品（如 2FA、AI 和 ML）并每月迭代？ 它们都使用 API 网关来分离问题 :)

Protocols

网关是您平台的唯一接口，还允许用户使用现代和更快的协议进行连接，例如 WebSocket 如果没有大的学习曲线，开发人员就会接触到（有时称为“回调地狱”）。 例如，WebSocket 是一种应用程序 协议，旨在取代 HTTP。 HTTP 实际上是一种文档协议，旨在托管文档，而不是应用程序）。

Clean separation of concerns

更重要的是，设计得当的网关可以将您的 SPA 清晰且合乎逻辑地划分为前端和后端，允许您交付设计正确、速度如闪电般的 SPA，使用更快的 CDN 提供静态消耗品。

将 CDN 用于前端负载意味着您​​只需关注后端的复杂性（前端的复杂性仅限于开发），而使用网关，您可以进一步降低除简单服务以外的所有内容的复杂性。

Reliability and security

此网关已用于许多产品：

• Support hundreds of thousands of connections at once using a single instance.
• Used behind a load balancer in a cluster of over 50 containers to house infinite connections on both GSP and AWS.
• It has been used to host tens of billions of records.
• It provides access to the half-terabyte legal database that powers openjurist.org, supplying millions of requests and approximately 1/3rd of all Wikipedia legal references.
• It is used by medical platforms to provide services for millions of patients.

Installation

<代码> npm i @acter/网关

Getting Started

<代码> const gateway = require('@acter/gateway')

这将为健康检查创建网关和设置端点（完全与 Kubernetes 或其他协调器兼容）。

它还将设置常见的应用默认设置和授权平台（使用 passport，因此您将能够使用 user/pass 对用户进行授权， JWT、Facebook、谷歌，你能想到的，你知道了）。 user/pass 和 JWT 是默认安装的，因为几乎每个人都使用它们。

Passport 支持超过 500 种授权机制。

Configuration

在项目的根目录中创建一个 /config 文件夹，其中包含一个名为 default.xml 的文件。 js。

该网关完全支持 node-config 中引入的所有丰富标准。

A word on folders

默认情况下，为了加快开发速度，网关希望您将配置放在 /config 文件夹中，将源代码放在 /src 文件夹中。 创建服务就像将文件放入 src/services 并使用配置启用它一样简单。

Default settings

这些是默认设置和值。 如果您要使用它们，则无需进行任何配置。

module.exports = {
  server: {
    // By default, will try port 8000 and use the next available, override here.
    port: 8000,
    // By default, will use your package.json version, but you can override here.
    version: '0.6.9',
    // Default will output fancy "Acter". Override here.
    logo: require('pathToYourLogoString'),
    // The datasource
    persistence: 'datasource://user:pas@host:port/db',
    // If we're hosting static files or not.
    statics: {
      host: false,
      endpoint: '/remote'.
      folder: 'statics' // The root of your source file + /statics
    }
  },
  services: {
    defaults: {
      model: {
        freezeTableName: true
      },
      pagination: {
        default: 20,
        max: 1000
      }
    },
    definitions: {
      yourServiecName: {
        model: 'yourModelName',
        auto: true // If true, your service will be auto-generated based on your mode.
        config: {
          // Configuration you pass to your service.
        }
      }
    }
  }
}

Connecting your data

Acter 为您提供了许多可以交互的数据源。 安装涉及一个简单的标准连接字符串：

datasource://user:pas@host:port/db

Where：

• datasource is one of the following: 'mysql', 'mariadb', 'postgres', 'sqlite', 'sqlserver'.
• user is the username authorized for the datasource.
• pass is the password authorized for the datasource.
• host is an IPv4, IPv6 or FDQN (like google.com) that your datasource is located at.
• port is optional, and only needed if using a nonstandard port for your datasource type.
• db is the name of the database at the host you provided.

就是这样！ 您现在可以完全访问 API 网关中的任何数据源。 这意味着您可以不再担心您使用的是哪个数据源，而是专注于您的应用程序。 例如，您可以使用一个简单的 sqlite 数据源启动一个应用程序，然后当您扩展、升级到 MySQL 时，您可以进一步扩展到 Postgres（Digital Ocean 托管托管等）或 MariaDB（Amazon Aurora、GCP 等） .

当您对数据源进行更改时，完全取决于您，您的源代码只会更改一行配置！ :)

有关如何创建服务和访问它们以及向世界公开您的数据的详细信息，请查看服务部分。

Other config options

server.statics

网关可以自动托管静态文件（比如 Apache/nginx，虽然稍微简单一点）:)。 为此，Express 处于幕后。 网关支持文件的 gzip 压缩、HTTP 或 HTTPS。 无需部署 NGINX 或 Apache 实例，或移动到 CDN，即可开始使用所需的一切。

默认

{ active: false, folder: 'statics, endpoint: '/remote }

active: 如果你想托管静态资源则为真（比如index.html）。

文件夹：您要托管的文件夹的相对路径。

端点：您要从中提供静态文件的端点。 '/' 代表 root，但将使用与您的服务相同的命名空间，并且可能会重叠或产生意外结果。

---

server.watch

网关可以自动监视文件夹的变化并将结果发送到您指定的脚本。 实现高级功能，例如在上传文件时更新 UI 等。

默认

{ active: false, folder: undefined, report: undefined }

active：如果您想观看文件夹，则为真。

文件夹：您要观看的文件夹的完整路径。

report：将接收有关您监视的文件夹的报告的脚本。

Report script.

您的报告脚本路径可以是相对的。 它将作为一个函数被调用并传递一个包含以下内容的对象：

{
  app,     // The app object, which lets you attach hooks or call any service
  watcher, // The watcher bus. More on this below
  config,  // The complete config for the gateway
  util     // The gateway util (helper functions) object
}

观察者总线是一个事件总线，它将触发以下事件：

• ready: You get this event when all the structure in the watched folder have been reported.
• add: Triggered when a file is added to a watched folder.
• unlink: Triggered when a file is removed from a watched folder.
• addDir: Triggered when a folder is added to a watched folder.
• unlinkDir: Triggered when a folder is removed from a watched folder.
• error: Triggered when something goes wrong.

所有事件都将传递更改的路径/文件，除了传递的ready什么都没有，error 传递错误对象。

Windows 用户注意：由于底层实现中的一个怪癖，Windows 操作系统在观看“unlinkedDir”时会报告错误。 NodeJS 没有考虑到这一点，也没有考虑到这一点（截至 2019 年 3 月 1 日）。 因此，Acter 无法自动干净地解决此问题。

如果你想在 Windows 机器上观看 unlinkedDir，添加一个错误触发器并像这样处理它......

        watcher.on('error', error => {
            // Ignore EPERM errors in windows, which happen if you delete folders...
            if (error.code === 'EPERM' && require('os').platform() === 'win32') return 
            // Otherwise, display the error...
            console.log(error)
        })

这个问题在 Mac 或 Linux 操作系统上不存在。

示例观察报告脚本......

module.exports = ({app, watcher, config, util}) => {
  watcher.on('ready', () => {
      // Can watch these events too: add, unlink, addDir, unlinkDir, error
      watcher.on('add', async path => {
        // As an example, get the total server memory percent used, and which file changed...
        const stat = await app.services.status.find()
        console.log(`(Mem used: ${stat.system.memory.percentUsed}). A new file has been uploaded: "${path}"`)
      })
  })    
}

console.log('Watcher script setup completed.')

server.port

默认

{ from: 8000, to: 8999 }

如果您指定一个数字，除非该端口空闲，否则服务器不会启动。 如果您使用带有“from”和“to”变量的对象指定范围（即 { from: startingPort, to: endingPort }），服务器将找到 该范围内的第一个自由港。 选择的端口将是 使用 config.server.port

server.mode

Default

http

可用于您的应用程序如果您指定“https”，服务器也将需要一个 key 和 cert 指向有效相应文件的值。 这就是激活 HTTPS 所需的全部。 如果启用 HTTPS，WebSocket 也会自动运行在 WSS 中， 使您的整个连接安全。 出于安全原因，您不能同时收听 HTTP 和 HTTPS。 如果你想这样做， 启动第二个网关。 我们认为隔离 HTTP/HTTPS 流量非常重要，我们认为您不应混合在两者中运行的代码。

Technical details

Entry point

acter 逻辑从 src/index.js 开始 绘制徽标，加载配置，启动平台。 Acter 在后台使用调试并以“acter”开头。

Logging

当您的服务执行 console.log() 语句时，它会在前面加上日期/时间戳并将其发送到标准输出。 使用任何服务管理策略将其记录的内容输出到文件或数据源。