From e4a1ad36e6ebd0cfdb4f27040e3ad29ce2750c00 Mon Sep 17 00:00:00 2001
From: JIN <i@imooc.me>
Date: Fri, 8 Jul 2022 19:28:14 +0800
Subject: [PATCH] add fluent query translation (#675)

* add fluent query translation
---
 docs/fluent/query.zh.md | 382 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 382 insertions(+)
 create mode 100644 docs/fluent/query.zh.md

diff --git a/docs/fluent/query.zh.md b/docs/fluent/query.zh.md
new file mode 100644
index 00000000..fa4435e4
--- /dev/null
+++ b/docs/fluent/query.zh.md
@@ -0,0 +1,382 @@
+# 查询
+
+Fluent 的查询 API 允许你从数据库中创建、读取、更新和删除模型。它支持过滤结果、连接、分块、聚合等。
+
+```swift
+// Fluent 查询 API 示例。
+let planets = try await Planet.query(on: database)
+    .filter(\.$type == .gasGiant)
+    .sort(\.$name)
+    .with(\.$star)
+    .all()
+```
+
+查询构建器与单个模型类型相关联，可以使用静态 [`query`](model.md#query) 方法创建。也可以通过将模型类型传递给数据库对象上的 `query` 方法来创建它们。
+
+```swift
+// 也可这样创建查询构建器。
+database.query(Planet.self)
+```
+
+!!! 注意
+    你需要在使用 query 语句的文件中使用 `import Fluent` 导入此框架，之后编译器便可以识别/提示相关联的函数。
+
+## All
+
+`all()` 方法返回一个模型数组。
+
+```swift
+// 获取所有的行星。
+let planets = try await Planet.query(on: database).all()
+```
+
+`all` 方法还支持从结果集中仅获取单个字段。
+
+```swift
+// 获取所有行星的名称。
+let names = try await Planet.query(on: database).all(\.$name)
+```
+
+### First
+
+`first()` 方法返回单个可选模型。如果查询结果有多个模型，则仅返回第一个模型。如果没有查询到结果，则返回 `nil`。
+
+```swift
+// 获取名称为地球的第一个行星。
+let earth = try await Planet.query(on: database)
+    .filter(\.$name == "Earth")
+    .first()
+```
+
+!!! 建议
+    如果使用`EventLoopFuture`，此方法可以与 [`unwrap(or:)`](../basics/errors.md#abort) 组合使用以返回非可选模型或抛出错误。
+
+## Filter
+
+`filter` 方法允许你约束结果集中包含的模型。此方法有几个重载方法。
+
+### Value Filter
+
+最常用的 `filter` 方法接受带有值的运算符表达式。
+
+```swift
+// 字段值过滤示例。
+Planet.query(on: database).filter(\.$type == .gasGiant)
+```
+
+这些运算符表达式接受左侧的字段键路径和右侧的值。所提供的值必须与字段的预期值类型相匹配，并绑定到结果查询。过滤表达式是强关联类型的，支持使用点语法。
+
+以下是所有受支持的值运算符的列表。
+
+|运算符|描述|
+|-|-|
+|`==`|相等。|
+|`!=`|不相等。|
+|`>=`|大于或等于。|
+|`>`|大于。|
+|`<`|小于。|
+|`<=`|小于或等于。|
+
+### Field Filter
+
+`filter` 方法支持比较两个字段。
+
+```swift
+// 查询姓和名相同的用户。
+User.query(on: database)
+    .filter(\.$firstName == \.$lastName)
+```
+
+字段过滤器支持与[值过滤](#value-filter)相同的运算符。
+
+### Subset Filter
+
+`filter` 方法支持检查字段的值是否存在于给定的一组值中。
+
+```swift
+// 查询所有气态行星或者小型岩石类型的行星。
+Planet.query(on: database)
+    .filter(\.$type ~~ [.gasGiant, .smallRocky])
+```
+
+提供的值集可以是任何 Swift 的 `Collection`，其 `Element` 类型与字段的值类型相匹配。
+
+以下是所有受支持的子集运算符的列表。
+
+|运算符|描述|
+|-|-|
+|`~~`|值在集中。|
+|`!~`|值不在集中。|
+
+### Contains Filter
+
+`filter` 方法支持检查字符串字段的值是否包含给定的子字符串。
+
+```swift
+// 查询所有名字以字母 M 开头的行星。
+Planet.query(on: database)
+    .filter(\.$name =~ "M")
+```
+
+这些运算符仅适用于具有字符串值的字段。
+
+下面是所有受支持的包含运算符的列表。
+
+|运算符|描述|
+|-|-|
+|`~~`|包含子字符串。|
+|`!~`|不包含子字符串。|
+|`=~`|匹配前缀。|
+|`!=~`|不匹配前缀。|
+|`~=`|配后后缀。|
+|`!~=`|不匹配后缀。|
+
+### Group
+
+默认情况下，添加到查询中的所有过滤器都必须匹配。查询构建器支持创建一组过滤器且有一个过滤器必须匹配。
+
+```swift
+// 查询的行星要么是地球要么是火星。
+Planet.query(on: database).group(.or) { group in
+    group.filter(\.$name == "Earth").filter(\.$name == "Mars")
+}.all()
+```
+
+`group` 方法支持通过 `and` 或 `or` 逻辑组合过滤器。这些组可以无限嵌套。顶级过滤器可以被认为是在一个 `and` 组中。
+
+## 聚合
+
+查询构建器支持多种方法来对一组值执行计算，例如计数或平均值。
+
+```swift
+// 数据库中存储的行星数量总和。
+Planet.query(on: database).count()
+```
+
+除了 `count` 之外，所有聚合方法都需要传递一个指向字段的键路径。
+
+```swift
+// 查询按名称排序后的最小值。
+Planet.query(on: database).min(\.$name)
+```
+
+下面是所有可用聚合方法的列表。
+
+|聚合|描述|
+|-|-|
+|`count`|结果计数。|
+|`sum`|结果求和。|
+|`average`|结果求平均数。|
+|`min`|结果中最小值。|
+|`max`|结果中最大值。|
+
+除 `count` 外，所有聚合方法都将返回字段的值类型作为结果。`count` 总是返回一个整数。
+
+## Chunk
+
+查询构建器支持将结果集作为单独的块返回。这有助于你在处理大型数据库读取时控制内存使用。
+
+```swift
+// 一次最多查询出64颗行星。
+Planet.query(on: self.database).chunk(max: 64) { planets in
+    // 处理查询到的行星数据
+}
+```
+
+根据结果的总数，所提供的闭包将被调用零次或多次。返回的每个项都是一个 `Result`，其中包含模型或试图解码数据库条目时返回的错误。
+
+## Field
+
+默认情况下，查询将从数据库中读取模型的所有字段。你可以选择使用 `field` 方法仅选择模型字段的子集。
+
+```swift
+// 只选择行星的 id 和 name 字段进行查询
+Planet.query(on: database)
+    .field(\.$id).field(\.$name)
+    .all()
+```
+
+在查询期间未选择的任何模型字段都将处于未初始化状态。尝试直接访问未初始化的字段将导致致命错误。要检查是否设置了模型的字段值，请使用 `value` 属性。
+
+```swift
+if let name = planet.$name.value {
+    // 行星名称有值
+} else {
+    // 行星名称没有值
+    // 访问 `planet.name` 会失败.
+}
+```
+
+## Unique
+
+查询构建器的 `unique` 方法只返回不同的结果（去重）。
+
+```swift
+// 去重后返回所有用户的名字。
+User.query(on: database).unique().all(\.$firstName)
+```
+
+`unique` 在获取带有 `all` 的单个字段时特别有用。但是，你也可以使用 [`field`](#field) 方法选择多个字段。由于模型标识符总是唯一的，所以在使用 `unique` 时应避免选择它们。
+
+## Range
+
+查询构建器的 `range` 方法允许你使用 Swift ranges 选择结果的子集。
+
+```swift
+// 查询前5颗行星。
+Planet.query(on: self.database)
+    .range(..<5)
+```
+
+范围值是从零开始的无符号整数。了解有关 [Swift ranges](https://developer.apple.com/documentation/swift/range) 的更多信息。
+
+```swift
+// 跳过前2个结果。
+.range(2...)
+```
+
+## Join
+
+查询构建器的 `join` 方法允许你在结果集中包含另一个模型的字段。可以将多个模型加入到你的查询中。
+
+```swift
+// 获取所有有太阳恒星的行星。
+Planet.query(on: database)
+    .join(Star.self, on: \Planet.$star.$id == \Star.$id)
+    .filter(Star.self, \.$name == "Sun")
+    .all()
+```
+
+`on` 参数接受两个字段之间的相等表达式。其中一个字段必须已经存在于当前结果集中。另一个字段必须存在于被连接的模型上。这些字段必须具有相同的值类型。
+
+大多数查询构建器方法，如 `filter` 和 `sort` 都支持连接模型。如果一个方法支持连接模型，它将接受连接模型类型作为第一个参数。
+
+```swift
+// 按 Star 模型上的 ”name“ 连接字段进行排序。
+.sort(Star.self, \.$name)
+```
+
+使用连接的查询仍将返回基本模型的数组。要访问连接模型，请使用 `joined` 方法。
+
+```swift
+// 从查询结果中访问连接模型。
+let planet: Planet = ...
+let star = try planet.joined(Star.self)
+```
+
+### 模型别名
+
+模型别名允许你多次将同一模型加入查询。要声明模型别名，请创建一个或多个遵循 `ModelAlias`协议的类型。
+
+```swift
+// 模型别名示例。
+final class HomeTeam: ModelAlias {
+    static let name = "home_teams"
+    let model = Team()
+}
+final class AwayTeam: ModelAlias {
+    static let name = "away_teams"
+    let model = Team()
+}
+```
+
+这些类型引用通过 `model` 属性别名的模型。创建之后，就可以像在查询构建器中使用普通模型一样使用模型别名。
+
+```swift
+// 获取主队名为 Vapor 的匹配项
+// 并按客场球队的名字排序。
+let matches = try await Match.query(on: self.database)
+    .join(HomeTeam.self, on: \Match.$homeTeam.$id == \HomeTeam.$id)
+    .join(AwayTeam.self, on: \Match.$awayTeam.$id == \AwayTeam.$id)
+    .filter(HomeTeam.self, \.$name == "Vapor")
+    .sort(AwayTeam.self, \.$name)
+    .all()
+```
+
+所有模型字段都可以通过 `@dynamicMemberLookup` 通过模型别名类型访问。
+
+```swift
+// 从查询结果中访问连接模型。
+let home = try match.joined(HomeTeam.self)
+print(home.name)
+```
+
+## Update
+
+查询构建器支持使用 `update` 方法一次更新多个模型。
+
+```swift
+// 更新所有名称为 ”Pluto“ 的行星。
+Planet.query(on: database)
+    .set(\.$type, to: .dwarf)
+    .filter(\.$name == "Pluto")
+    .update()
+```
+
+`update` 支持 `set`、`filter` 和 `range` 方法。
+
+## Delete
+
+查询构建器支持使用 `delete` 方法一次删除多个模型。
+
+```swift
+// 删除所有名称为 ”Vulcan“ 的行星。
+Planet.query(on: database)
+    .filter(\.$name == "Vulcan")
+    .delete()
+```
+
+`delete` 支持 `filter` 方法。
+
+## Paginate
+
+Fluent 的查询 API 支持使用 `paginate` 方法进行自动结果分页。
+
+```swift
+// 基于请求的分页示例。
+app.get("planets") { req in
+    try await Planet.query(on: req.db).paginate(for: req)
+}
+```
+
+`paginate(for:)` 方法将使用请求 URI 中可用的 `page` 和 `per` 参数来返回所需的结果集。关于当前页面和结果总数的元数据包含在 `metadata` 键中。
+
+```http
+GET /planets?page=2&per=5 HTTP/1.1
+```
+
+上述请求将产生如下结构的响应。
+
+```json
+{
+    "items": [...],
+    "metadata": {
+        "page": 2,
+        "per": 5,
+        "total": 8
+    }
+}
+```
+
+页码从`1`开始。你也可以手动请求页面。
+
+```swift
+// 手动分页请求示例。
+.paginate(PageRequest(page: 1, per: 2))
+```
+
+## Sort
+
+查询结果可以使用 `sort` 方法按字段值排序。
+
+```swift
+// 查询所有行星按照名称进行排序。
+Planet.query(on: database).sort(\.$name)
+```
+
+如果出现并列相等，可以添加额外的排序作为后备。回退将按照它们添加到查询构建器的顺序使用。
+
+```swift
+// 查询所有用户并按姓名进行排序，如果姓名相同，在按照年龄排序。
+User.query(on: database).sort(\.$name).sort(\.$age)
+```