核心概念

资源

资源是指你的应用程序通过HTTP API暴露出来的东西。资源可以是任何东西--应用程序中的用户配置文件，南极洲的温度传感器，或者游戏的高分。例如，GitHub API 暴露的是组织、存储库、问题和拉动请求资源；社交网络 API 有配置文件、帖子和用户关系。

资源被组织成集合（例如，所有的帖子），对于该集合中的单个资源可以被唯一标识（例如，单个帖子）。向应用程序提出请求，以检索资源的状态或提供所需的资源状态。大多数情况下，资源被表示为JSON数组和对象。当检索资源时，它的JSON表示方式被编码到响应体中。当提供资源的所需状态时，客户端在请求体中发送所需资源状态的JSON表示。

有关资源概念的更多细节，请参阅RFC Specification for HTTP/1.1。

路由

资源是通过HTTP请求的路径来识别的。例如，URLhttp://example.com/organizations标识服务器http://example.com上组织资源的集合。 URLhttp://example.com/organizations/1标识单个组织。

一个应用程序为它所管理的每个资源公开路由。路由是一个与请求的路径匹配的字符串。当一个请求的路径与路由匹配时，相关的处理程序被调用来处理该请求。路由看起来像路径，但有一些额外的语法。例如，路由 /organizations将匹配路径为/organizations的请求。路由/organizations/:id将匹配路径/organizations/1、/organizations/2等路径。

复杂的路由可以用附加语法形成。详细使用方法请参见routing指南。

控制器

控制器是处理请求的对象。例如，一个控制器可能从数据库中获取行，并在响应体中将其发送给客户端。另一个控制器可能验证请求的授权头中的用户名和密码是否有效。

控制器被链接在一起，形成了一系列要对一个请求采取的操作。这些链接在一起的控制器称为通道。如果将上述示例链接在一起，则该通道将在发送包含数据库行的响应之前检查请求是否得到授权。

有两种类型的控制器。端点控制器对资源或资源集合执行操作，并总是发送一个响应。端点控制器通过返回资源的状态或改变资源的状态来实现请求。由你来编写大多数特定于应用程序的逻辑端点控制器。

中间件控制器为请求采取一个动作，但不负责完成请求。中间件控制器可以做很多不同的事情，并且通常可以在许多通道中重用。通常，中间件控制器会在请求到达端点控制器之前先对其进行验证。中间件控制器可以发送对请求的响应，这样做可以防止该通道中的任何其他控制器处理该请求。

一个通道必须只有一个端点控制器。它的前面可以有零个或多个中间件控制器。有关使用细节，请参阅Controllers和ResourceControllers指南。

应用程序通道

应用程序通道是一个对象，它包含了一个应用中的所有控制器。它指定一个控制器作为第一个接收每个请求的控制器，称为它的入口点。控制器与入口点相连（直接或中转），构成了整个应用通道。在几乎所有的应用中，入口点是一个路由器；这个控制器将通道分成给定路由的子通道。

应用程序通道还负责初始化应用程序的服务，读取配置文件和其他与启动有关的任务。有关更多详细信息，请参见Application Channel上的指南。

服务

服务是一个封装复杂任务或算法、外部通信或任务的对象，这些任务将在整个应用中重复使用。服务对象的目的是提供一个简单的接口来实现更详细的行为。例如，数据库连接就是一个服务对象；数据库连接的用户不知道连接的细节，也不知道如何将查询编码到网络上，但它仍然可以执行查询。

服务对象的主要用户是控制器。服务是通过将服务作为参数传递给控制器的构造函数来注入控制器的。控制器保留了对服务的引用，以便在处理请求时可以使用它。

关于注入服务的详细信息，请参阅Application Channel上的指南。

Isolates

Isolate是内存隔离的线程；在一个Isolate上创建的对象不能被另一个Isolate引用。当应用程序启动时，一个或多个包含应用程序代码副本的隔离线程会被生成。这种行为可以有效地在多个线程之间实现应用程序的 "负载平衡"。

这种结构的一个好处是，每个隔离体都有自己的服务集，比如数据库连接。这消除了像 "数据库连接池化 "这样的技术，因为整个应用程序有效地 "池化 "了。

绑定

请求可能包含标头，查询参数，主体和路径参数，这些参数需要在控制器代码中进行解析，验证和使用。绑定是添加到变量的注释，这些注释会自动执行此解析和验证。当绑定值无法解析为预期类型或验证失败时，将发送适当的错误响应。

绑定减少了样板代码并减少了测试面，从而使开发更快且代码更易于推理。有关绑定的更多信息，请参见Resource Controllers上的指南。

查询和数据模型

应用程序将信息存储在数据库中进行持久化。手工编写数据库查询容易出错，而且不能利用静态分析工具，而静态分析工具在Dart应用中是非常有价值的。Aqueduct的ORM（对象关系映射）提供了静态类型的查询，易于编写和测试。

应用程序的数据模型是通过创建Dart类来定义的。每个类被映射到一个数据库表，该类的每个属性被映射到该表的一个列。Aqueduct的命令行工具会生成数据库迁移文件，检测到数据模型中的变化，并将其应用到实时的、版本化的数据库中。数据模型也可以表示为JSON对象，以在应用程序之上构建工具。

更多详情，请参阅数据库上的指南。

授权

OAuth 2.0是一个标准化的授权框架。Aqueduct包含了一个符合规范的OAuth2.0服务器实现，它可以直接集成到你的应用程序中，也可以单独为联合服务提供授权服务器。此实现易于定制-它可以将授权工件（例如令牌和客户端标识符）存储在不同类型的数据库中，或使用无状态授权机制（例如JWT）。默认实现利用Aqueduct ORM在PostgreSQL中存储工件。

更多详情，请参阅授权指南。

文档

OpenAPI 3.0是HTTP API的标准化文档格式。许多内置的Aqueduct对象支持 "自动 "文档。可以在此基础上构建特定于应用程序的对象，以便为你的应用程序的每一个变化立即记录下来。

更多详情，请参阅OpenAPI文档上的指南。