mirror of https://github.com/vapor/docs.git
593 lines
18 KiB
Markdown
593 lines
18 KiB
Markdown
# 模型
|
||
|
||
模型表示存储在数据库中的表或集合中的数据。模型有一个或多个存储可编码值的字段。所有模型都有唯一的标识符。属性包装器用于表示标识符、字段和关系。
|
||
|
||
下面示例是一个具有一个字段的简单模型。请注意，模型并不描述整个数据库模式，例如约束、索引和外键。[迁移](migration.zh.md)中有对模式的定义。模型专注于表示存储在数据库模式中的数据。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 集合或者表名。
|
||
static let schema = "planets"
|
||
|
||
// 行星的唯一标识符
|
||
@ID(key: .id)
|
||
var id: UUID?
|
||
|
||
// 行星名称。
|
||
@Field(key: "name")
|
||
var name: String
|
||
|
||
// 初始化一个空的行星。
|
||
init() { }
|
||
|
||
// 初始化行星并设置所有属性。
|
||
init(id: UUID? = nil, name: String) {
|
||
self.id = id
|
||
self.name = name
|
||
}
|
||
}
|
||
```
|
||
|
||
## 模式(Schema)
|
||
|
||
所有模型都需要一个静态常量 `schema` 属性。此字符串引用此模型表示的表或集合的名称。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 表或集合名
|
||
static let schema = "planets"
|
||
}
|
||
```
|
||
|
||
在查询该模型时，数据将从名为 `planets` 的模式中获取并存储到该模式中。
|
||
|
||
!!! tip "建议"
|
||
模式名称通常是复数和小写的类名称。
|
||
|
||
## 标识符
|
||
|
||
所有模型都必须有一个使用 `@ID` 属性包装器定义的 `id` 属性。该字段标识模型实例的唯一性。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 该行星的唯一标识符。
|
||
@ID(key: .id)
|
||
var id: UUID?
|
||
}
|
||
```
|
||
|
||
默认情况下，`@ID` 属性应使用特殊 `.id` 键，对底层数据库驱动程序来说该键会被解析为合适的键。对于 SQL 是这样 `"id"`，对于 NoSQL 是 `"_id"`。
|
||
|
||
`@ID` 的类型是 `UUID` 类型。这是所有数据库驱动程序当前支持的唯一标识符值。创建模型时 Fluent 会自动生成一个 UUID 标识符。
|
||
|
||
`@ID` 有一个可选值，因为未保存的模型可能还没有标识符。要获取标识符或引发错误，请使用 `requireID` 方法获取。
|
||
|
||
```swift
|
||
let id = try planet.requireID()
|
||
```
|
||
|
||
### Exists
|
||
|
||
`@ID` 有一个 `exists` 属性表示模型是否存在于数据库中。初始化模型时，值为 `false`。保存模型后或从数据库中获取模型时，值为 `true`。该属性是可变的。
|
||
|
||
```swift
|
||
if planet.$id.exists {
|
||
// 数据库中已经存在该模型
|
||
}
|
||
```
|
||
|
||
### 自定义标识符(Custom Identifier)
|
||
|
||
Fluent 支持使用 `@ID(custom:)` 属性包装器自定义标识符键和类型。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 行星的唯一标识符。
|
||
@ID(custom: "foo")
|
||
var id: Int?
|
||
}
|
||
```
|
||
|
||
上面的示例使用带有自定义键 `"foo"` 的 `@ID` 属性且标识符类型为 `Int`。这与使用自增主键的 SQL 数据库兼容，但与 NoSQL 不兼容。
|
||
|
||
自定义 `@ID` 允许用户指定如何使用 `generatedBy` 参数生成标识符。
|
||
|
||
```swift
|
||
@ID(custom: "foo", generatedBy: .user)
|
||
```
|
||
|
||
`generatedBy` 参数支持以下情况：
|
||
|
||
|生成方式|描述|
|
||
|-|-|
|
||
|`.user`|`@ID` 属性预计在保存新模型之前设置。|
|
||
|`.random`|`@ID` 值类型必须遵循 `RandomGeneratable` 协议。|
|
||
|`.database`|数据库应在保存时生成一个值。|
|
||
|
||
如果省略了 `generatedBy` 参数，Fluent 将尝试根据 `@ID` 值类型推断出适当的情况。例如，除非另有说明，否则 `Int` 将默认生成 `.database`。
|
||
|
||
## 初始化器
|
||
|
||
模型必须有一个空的初始化方法。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 初始化一个空的行星。
|
||
init() { }
|
||
}
|
||
```
|
||
|
||
Fluent 在内部需要此方法来初始化查询返回的模型。它也用于反射。
|
||
|
||
你可能希望添加一个便利构造器初始化时接收所有属性。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 初始化行星时设置所有属性。
|
||
init(id: UUID? = nil, name: String) {
|
||
self.id = id
|
||
self.name = name
|
||
}
|
||
}
|
||
```
|
||
|
||
使用便利构造器将来可以更轻松地向模型添加新属性。
|
||
|
||
## 字段
|
||
|
||
模型可以具有零个或多个 `@Field` 用于存储数据的属性。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 行星名
|
||
@Field(key: "name")
|
||
var name: String
|
||
}
|
||
```
|
||
|
||
字段需要明确定义数据库键。这不需要与属性名称相同。
|
||
|
||
!!! tip "建议"
|
||
Fluent 建议使用 `蛇形命名法` 命名数据库键和 `驼峰命名法` 命名属性名称。
|
||
|
||
字段值可以是任何遵循 `Codable` 协议类型。`@Field` 支持存储嵌套结构和数组，但过滤操作受到限制。请参阅 [@Group](#group) 替代方案。
|
||
|
||
对于包含可选值的字段，请使用 `@OptionalField`。
|
||
|
||
```swift
|
||
@OptionalField(key: "tag")
|
||
var tag: String?
|
||
```
|
||
|
||
!!! warning "警告"
|
||
一个非可选字段如果有一个引用其当前值的 `willSet` 属性观察者，或者一个引用其 `oldValue` 属性的 `didSet` 属性观察者，将导致致命错误。
|
||
|
||
## 关系
|
||
|
||
模型可以有零个或多个关联属性，它们引用其他模型，比如 `@Parent`，`@Children` 和 `@Siblings`。参阅[关系](relations.zh.md)了解更多信息。
|
||
|
||
## 时间戳
|
||
|
||
`@Timestamp` 是 `@Field` 的一种特殊类型，它存储 `Foundation.Date`。Fluent 根据选择的触发器自动设置时间戳。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 当创建行星时。
|
||
@Timestamp(key: "created_at", on: .create)
|
||
var createdAt: Date?
|
||
|
||
// 当行星最后一次更新时。
|
||
@Timestamp(key: "updated_at", on: .update)
|
||
var updatedAt: Date?
|
||
}
|
||
```
|
||
|
||
`@Timestamp` 支持以下触发器。
|
||
|
||
|触发器|描述|
|
||
|-|-|
|
||
|`.create`|在将新模型实例保存到数据库时设置。|
|
||
|`.update`|将现有模型实例保存到数据库时设置。|
|
||
|`.delete`|从数据库中删除模型时设置。请参阅[软删除](#soft-delete)。|
|
||
|
||
`@Timestamp` 的日期值是可选的，初始化新模型时应该设置为 `nil`。
|
||
|
||
### 时间戳格式化
|
||
|
||
默认情况下，`@Timestamp` 将根据数据库驱动程序使用有效的 `datetime` 编码。你可以使用 `format` 参数自定义时间戳在数据库中的存储方式。
|
||
|
||
```swift
|
||
// 存储ISO 8601格式的时间戳
|
||
// 此模型最后一次更新的时间。
|
||
@Timestamp(key: "updated_at", on: .update, format: .iso8601)
|
||
var updatedAt: Date?
|
||
```
|
||
|
||
请注意，此 `.iso8601` 示例的关联迁移需要以 `.string` 格式存储。
|
||
|
||
```swift
|
||
.field("updated_at", .string)
|
||
```
|
||
|
||
下面列出了可用的时间戳格式。
|
||
|
||
|格式化|描述|类型|
|
||
|-|-|-|
|
||
|`.default`|对特定数据库使用有效 `datetime` 的编码。 |Date|
|
||
|`.iso8601`|[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 字符串。支持 `withMilliseconds` 参数。|String|
|
||
|`.unix`|从 Unix 纪元开始的秒数，包括分数。|Double|
|
||
|
||
你可以使用 `timestamp` 属性直接访问原始时间戳值。
|
||
|
||
```swift
|
||
// 手动设置 ISO 8601上的时间戳值
|
||
// 格式化 @Timestamp.
|
||
model.$updatedAt.timestamp = "2020-06-03T16:20:14+00:00"
|
||
```
|
||
|
||
### 软删除(Soft Delete)
|
||
|
||
模型中添加一个使用 `.delete` 触发器的 `@Timestamp`，将启用软删除。
|
||
|
||
```swift
|
||
final class Planet: Model {
|
||
// 当这个行星被删除的时候。
|
||
@Timestamp(key: "deleted_at", on: .delete)
|
||
var deletedAt: Date?
|
||
}
|
||
```
|
||
|
||
软删除的模型在删除后仍然存在于数据库中，但不会在查询中返回。
|
||
|
||
!!! tip "建议"
|
||
你可以手动将删除时间戳设置为将来的日期。这可以用作到期日期。
|
||
|
||
要强制从数据库中删除可软删除的模型，请使用 `delete` 方法的 `force` 参数。
|
||
|
||
```swift
|
||
// 从数据库中删除，即使模型是软删除的。
|
||
model.delete(force: true, on: database)
|
||
```
|
||
|
||
要恢复软删除的模型，请使用 `restore` 方法。
|
||
|
||
```swift
|
||
// 清除软删除模型的时间戳，允许查询时返回该模型。
|
||
model.restore(on: database)
|
||
```
|
||
|
||
要在查询中包含软删除的模型，请使用 `withDeleted` 方法。
|
||
|
||
```swift
|
||
// 获取所有行星，包括软删除的行星。
|
||
Planet.query(on: database).withDeleted().all()
|
||
```
|
||
|
||
## 枚举
|
||
|
||
`@Enum` 是 `@Field` 的一种特殊类型，用于将字符串可表示类型存储为原生数据库枚举。原生数据库枚举为你的数据库提供了额外的类型安全层，可能比原始枚举性能更好。
|
||
|
||
```swift
|
||
// 动物类型遵循 String，Codable 协议。
|
||
enum Animal: String, Codable {
|
||
case dog, cat
|
||
}
|
||
|
||
final class Pet: Model {
|
||
// 将动物类型存储为原生数据库枚举。
|
||
@Enum(key: "type")
|
||
var type: Animal
|
||
}
|
||
```
|
||
|
||
只有当 `RawValue` 为 `String` 时，遵循 `rawrepresentation` 协议的类型才与 `@Enum` 兼容。默认情况下，由 `String` 支持的枚举满足此要求。
|
||
|
||
使用 `@OptionalEnum`，存储可选枚举。
|
||
|
||
数据库必须准备好通过迁移处理枚举。请参阅[枚举](schema.zh.md#enum)了解更多信息。
|
||
|
||
### 原始枚举
|
||
|
||
任何由遵循 `Codable` 协议的类型支持的枚举，比如 `String` 或 `Int`，都可以存储在 `@Field` 中。它将作为原始值存储在数据库中。
|
||
|
||
## 组(Group)
|
||
|
||
`@Group` 允许你将嵌套的一组字段作为单个属性存储在模型中。与存储在 `@Field` 中的可编码结构不同，`@Group` 中的字段是可查询的。Fluent 通过将 `@Group` 作为平面结构存储在数据库中来实现这一点。
|
||
|
||
要使用 `@Group`，首先定义要使用 `Fields` 协议存储的嵌套结构。这与 `Model` 非常相似，只是不需要标识符或模式名称。你可以在这里存储许多 `Model` 支持的属性，比如 `@Field`，`@Enum`，甚至另一个 `@Group`。
|
||
|
||
```swift
|
||
// 带有名称和动物类型的宠物。
|
||
final class Pet: Fields {
|
||
// 宠物名。
|
||
@Field(key: "name")
|
||
var name: String
|
||
|
||
// 宠物类型。
|
||
@Field(key: "type")
|
||
var type: String
|
||
|
||
// 创建一个空的宠物。
|
||
init() { }
|
||
}
|
||
```
|
||
|
||
创建字段定义后，你可以将其用作 `@Group` 属性的值。
|
||
|
||
```swift
|
||
final class User: Model {
|
||
// 用户的宠物。
|
||
@Group(key: "pet")
|
||
var pet: Pet
|
||
}
|
||
```
|
||
|
||
`@Group` 的字段可以通过点语法访问。
|
||
|
||
```swift
|
||
let user: User = ...
|
||
print(user.pet.name) // 字符串
|
||
```
|
||
|
||
你可以像往常一样使用属性包装器上的点语法查询嵌套字段。
|
||
|
||
```swift
|
||
User.query(on: database).filter(\.$pet.$name == "Zizek").all()
|
||
```
|
||
|
||
在数据库中，`@Group` 存储为一个平面结构，键由 `_` 连接。 下面是一个关于 `User` 模型在数据库中存储样子的例子。
|
||
|
||
|id|name|pet_name|pet_type|
|
||
|-|-|-|-|
|
||
|1|Tanner|Zizek|Cat|
|
||
|2|Logan|Runa|Dog|
|
||
|
||
## Codable
|
||
|
||
模型默认遵循 `Codable` 协议。这意味着你可以通过添加 `Content` 协议将你的模型与 Vapor 的 [content API](../basics/content.zh.md) 一起使用。
|
||
|
||
```swift
|
||
extension Planet: Content { }
|
||
|
||
app.get("planets") { req async throws in
|
||
// 返回一个包含所有行星的数组。
|
||
try await Planet.query(on: req.db).all()
|
||
}
|
||
```
|
||
|
||
当从 `Codable` 序列化时，模型属性将使用它们的变量名而不是键。关系将序列化为嵌套结构，并将包括任何预先加载的数据。
|
||
|
||
### 数据传输对象
|
||
|
||
模型默认遵循 `Codable` 协议的一致性使它变得易于使用且原型制作更容易。然而，它并不适用于每一个用例。在某些情况下，需要使用数据传输对象 (DTO)。
|
||
|
||
!!! tip "建议"
|
||
DTO 是一种单独的 `Codable` 类型，表示你想要编码或解码的数据结构。
|
||
|
||
接下来的示例中，`User` 模型如下所示。
|
||
|
||
```swift
|
||
// 删节的用户模型供参考。
|
||
final class User: Model {
|
||
@ID(key: .id)
|
||
var id: UUID?
|
||
|
||
@Field(key: "first_name")
|
||
var firstName: String
|
||
|
||
@Field(key: "last_name")
|
||
var lastName: String
|
||
}
|
||
```
|
||
|
||
DTO 的一个常见用例是实现 `PATCH` 请求。这些请求只包含应该更新的字段的值。如果缺少任何必填的字段，尝试直接从这样的请求解码 `Model` 将会失败。在下面的示例中，你可以看到一个 DTO 用于解码请求数据和更新模型。
|
||
|
||
```swift
|
||
// PATCH 请求结构 /users/:id。
|
||
struct PatchUser: Decodable {
|
||
var firstName: String?
|
||
var lastName: String?
|
||
}
|
||
|
||
app.patch("users", ":id") { req async throws -> User in
|
||
// 解码请求数据。
|
||
let patch = try req.content.decode(PatchUser.self)
|
||
// 从数据库中获取所需的用户。
|
||
guard let user = try await User.find(req.parameters.get("id"), on: req.db) else {
|
||
throw Abort(.notFound)
|
||
}
|
||
// 如果提供了名字，则更新它。
|
||
if let firstName = patch.firstName {
|
||
user.firstName = firstName
|
||
}
|
||
// 如果提供了新的姓氏，则更新它。
|
||
if let lastName = patch.lastName {
|
||
user.lastName = lastName
|
||
}
|
||
// 保存并返回用户信息
|
||
try await user.save(on: req.db)
|
||
return user
|
||
}
|
||
```
|
||
|
||
DTO 的另一个常见用例是自定义 API 响应的格式。下面的示例显示了如何使用 DTO 将计算字段添加到响应中。
|
||
|
||
```swift
|
||
// GET 请求响应结构 /users。
|
||
struct GetUser: Content {
|
||
var id: UUID
|
||
var name: String
|
||
}
|
||
|
||
app.get("users") { req async throws -> [GetUser] in
|
||
// 从数据库获取所有用户。
|
||
let users = try await User.query(on: req.db).all()
|
||
return try users.map { user in
|
||
// 将每个用户转换为 GET 返回类型。
|
||
try GetUser(
|
||
id: user.requireID(),
|
||
name: "\(user.firstName) \(user.lastName)"
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
即使 DTO 的结构与模型的 `Codable` 协议一致性相同，将其作为一个单独的类型也有助于保持大型项目的整洁。如果你需要修改模型属性，则不必担心破坏应用程序的公共 API。你还可以考虑将 DTO 放在一个单独的包中，该包可以与你的 API 使用者共享。
|
||
|
||
由于这些原因，我们强烈建议尽可能使用 DTO，尤其是对于大型项目。
|
||
|
||
## 别名
|
||
|
||
`ModelAlias` 协议允许你在查询中唯一地标识要多次连接的模型。请参阅 [joins](query.zh.md#join) 了解更多信息。
|
||
|
||
## 保存
|
||
|
||
要将模型保存到数据库，请使用 `save(on:)` 方法。
|
||
|
||
```swift
|
||
planet.save(on: database)
|
||
```
|
||
|
||
此方法会根据模型是否已存在于数据中在内部调用 `create` 方法或者 `update` 方法。
|
||
|
||
### 创建
|
||
|
||
你可以调用 `create` 方法将新模型保存到数据库中。
|
||
|
||
```swift
|
||
let planet = Planet(name: "Earth")
|
||
planet.create(on: database)
|
||
```
|
||
|
||
`create` 也可用于模型数组。这将在单个批处理/查询中将所有模型保存到数据库中。
|
||
|
||
```swift
|
||
// 批量创建示例。
|
||
[earth, mars].create(on: database)
|
||
```
|
||
|
||
!!! warning "警告"
|
||
模型使用 [`@ID(custom:)`](#custom-identifier) 和 `.database` 生成器(通常是自动递增的 `Int` 型)时在批处理创建后将无法访问其新创建的标识符。对于需要访问标识符的情况，在每个模型上调用 `create` 方法。
|
||
|
||
要单独创建模型数组，请使用 `map` + `flatten`。
|
||
|
||
```swift
|
||
[earth, mars].map { $0.create(on: database) }
|
||
.flatten(on: database.eventLoop)
|
||
```
|
||
|
||
如果使用 `async`/`await` 你可以使用：
|
||
|
||
```swift
|
||
await withThrowingTaskGroup(of: Void.self) { taskGroup in
|
||
[earth, mars].forEach { model in
|
||
taskGroup.addTask { try await model.create(on: database) }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 更新
|
||
|
||
你可以调用 `update` 方法来保存从数据库中获取的模型。
|
||
|
||
```swift
|
||
guard let planet = try await Planet.find(..., on: database) else {
|
||
throw Abort(.notFound)
|
||
}
|
||
planet.name = "Earth"
|
||
try await planet.update(on: database)
|
||
```
|
||
|
||
要更新模型数组，请使用 `map` + `flatten`。
|
||
|
||
```swift
|
||
[earth, mars].map { $0.update(on: database) }
|
||
.flatten(on: database.eventLoop)
|
||
|
||
// TOOD
|
||
```
|
||
|
||
## 查询(Query)
|
||
|
||
模型公开了一个 `query(on:)` 静态方法返回查询构建器。
|
||
|
||
```swift
|
||
Planet.query(on: database).all()
|
||
```
|
||
|
||
了解查询相关的更多信息，请参阅[查询](query.zh.md)章节。
|
||
|
||
## 查找
|
||
|
||
模型的 `find(_:on:)` 静态方法，通过标识符查找模型实例。
|
||
|
||
```swift
|
||
Planet.find(req.parameters.get("id"), on: database)
|
||
```
|
||
|
||
如果没有找到具有该标识符的模型，则返回 `nil`。
|
||
|
||
## 生命周期(Lifecycle)
|
||
|
||
模型中间件允许你监听模型的生命周期事件。支持以下生命周期事件。
|
||
|
||
|方法|描述|
|
||
|-|-|
|
||
|`create`|在创建模型之前运行。|
|
||
|`update`|在模型更新之前运行。|
|
||
|`delete(force:)`|在删除模型之前运行。|
|
||
|`softDelete`|在模型被软删除之前运行。|
|
||
|`restore`|在模型恢复之前运行(与软删除相反)。|
|
||
|
||
|
||
模型中间件使用 `ModelMiddleware` 或 `AsyncModelMiddleware` 协议声明。所有生命周期方法都有一个默认实现，因此你只需要实现所需的方法。每个方法都接受有问题的模型、对数据库的引用以及链中的下一个操作。中间件可以选择提前返回，返回失败的 future，或者调用下一个操作正常继续。
|
||
|
||
使用这些方法，你可以在特定事件完成之前和之后执行操作。在事件完成后执行操作可以通过映射从下一个响应者返回的 future 来完成。
|
||
|
||
```swift
|
||
// 名称大写的中间件示例。
|
||
struct PlanetMiddleware: ModelMiddleware {
|
||
func create(model: Planet, on db: Database, next: AnyModelResponder) -> EventLoopFuture<Void> {
|
||
// 在创建模型之前，可以在这里修改模型。
|
||
model.name = model.name.capitalized()
|
||
return next.create(model, on: db).map {
|
||
//一旦行星被创建，代码将被执行。
|
||
print ("Planet \(model.name) was created")
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
或者如果使用 `async`/`await`：
|
||
|
||
```swift
|
||
struct PlanetMiddleware: AsyncModelMiddleware {
|
||
func create(model: Planet, on db: Database, next: AnyAsyncModelResponder) async throws {
|
||
// 在创建模型之前，可以在这里修改模型。
|
||
model.name = model.name.capitalized()
|
||
try await next.create(model, on: db)
|
||
//一旦行星被创建，代码将被执行。
|
||
print ("Planet \(model.name) was created")
|
||
}
|
||
}
|
||
```
|
||
|
||
创建中间件后，你可以使用 `app.databases.middleware` 来启用它.
|
||
|
||
```swift
|
||
// 配置模型中间件示例。
|
||
app.databases.middleware.use(PlanetMiddleware(), on: .psql)
|
||
```
|
||
|
||
## 数据库空间(Database Space)
|
||
|
||
Fluent 支持为模型设置空间，这允许在 PostgreSQL 模式、MySQL 数据库和多个附加的 SQLite 数据库之间对单个 Fluent 模型进行分区。在撰写本文时，MongoDB 还不支持空间。为了将模型放置在一个非默认空间中，向模型添加一个新的静态属性:
|
||
|
||
```swift
|
||
public static let schema = "planets"
|
||
public static let space: String? = "mirror_universe"
|
||
|
||
// ...
|
||
```
|
||
Fluent 将在构建所有数据库查询时使用它。
|