add advanced apns translation (#690)

* add fluent advanced translation * 修改部分翻译 * add leaf getting-started translation and fix api link is 404 * 修改一些翻译 * add leaf custom tags translation * add leaf overview translation * add advanced apns translation * add advanced server translation * Fix translation * Fix translation
2022-07-27 21:44:32 +08:00 · 2022-07-27 21:44:32 +08:00 · 2fc2a299e0
parent c717d69574
commit 2fc2a299e0
2 changed files with 381 additions and 0 deletions
--- a/docs/advanced/apns.zh.md
+++ b/docs/advanced/apns.zh.md
@ -0,0 +1,148 @@
+# APNS
+
+在 Vapor 中使用基于 [APNSwift](https://github.com/kylebrowning/APNSwift) 构建的 API，可以轻松实现 Apple 推送通知服务(APNS) 的身份验证并将推送通知发送到 Apple 设备。
+
+## 入门
+
+让我们看看如何使用 APNS。
+
+### Package
+
+使用 APNS 的第一步是将此依赖项添加到你的 Package.swift 文件中。
+
+```swift
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "my-app",
+    dependencies: [
+         // Other dependencies...
+        .package(url: "https://github.com/vapor/apns.git", from: "3.0.0"),
+    ],
+    targets: [
+        .target(name: "App", dependencies: [
+            // Other dependencies...
+            .product(name: "APNS", package: "apns")
+        ]),
+        // Other targets...
+    ]
+)
+```
+
+如果你直接在 Xcode 中编辑清单文件，它会在文件保存时自动提取更改并获取新的依赖项。否则，从终端运行 `swift package resolve` 命令来获取新的依赖项。
+
+### 配置
+
+APNS 模块为 `Application` 添加了一个 `apns` 新属性。要发送推送通知，你需要设置 `configuration` 属性的认证凭证。
+
+```swift
+import APNS
+
+// 使用 JWT 认证 配置 APNS。
+app.apns.configuration = try .init(
+    authenticationMethod: .jwt(
+        key: .private(filePath: <#path to .p8#>),
+        keyIdentifier: "<#key identifier#>",
+        teamIdentifier: "<#team identifier#>"
+    ),
+    topic: "<#topic#>",
+    environment: .sandbox
+)
+```
+
+在占位符中填写你的凭据。上面的示例显示了[基于 JWT 的认证](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_token-based_connection_to_apns)方式，使用从 Apple 开发者官网获得的 `.p8` 密钥。对于[基于 TLS 的认证](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns)，请使用 `.tls` 身份验证方法：
+
+```swift
+authenticationMethod: .tls(
+    privateKeyPath: <#path to private key#>,
+    pemPath: <#path to pem file#>,
+    pemPassword: <#optional pem password#>
+)
+```
+
+### 发送
+
+配置 APNS 后，你可以使用 `apns.send` 方法在 `Application` 或 `Request` 中发送推送通知。
+
+```swift
+// 发送一条推送。
+try app.apns.send(
+    .init(title: "Hello", subtitle: "This is a test from vapor/apns"),
+    to: "98AAD4A2398DDC58595F02FA307DF9A15C18B6111D1B806949549085A8E6A55D"
+).wait()
+
+// 或者
+try await app.apns.send(
+    .init(title: "Hello", subtitle: "This is a test from vapor/apns"),
+    to: "98AAD4A2398DDC58595F02FA307DF9A15C18B6111D1B806949549085A8E6A55D"
+)
+```
+
+每当你在路由内部处理时，使用 `req.apns` 发送推送通知。
+
+```swift
+// 发送推送通知
+app.get("test-push") { req -> EventLoopFuture<HTTPStatus> in
+    req.apns.send(..., to: ...)
+        .map { .ok }
+}
+
+// 或者
+app.get("test-push") { req async throws -> HTTPStatus in
+    try await req.apns.send(..., to: ...) 
+    return .ok
+}
+```
+
+第一个参数接受推送通知的数据，第二个参数是目标设备令牌。
+
+## Alert
+
+`APNSwiftAlert` 是要发送的推送通知的实际元数据。[此处](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html)提供了每个属性的详细信息。它们遵循 Apple 文档中列出的一对一命名方案。
+
+```swift
+let alert = APNSwiftAlert(
+    title: "Hey There", 
+    subtitle: "Full moon sighting", 
+    body: "There was a full moon last night did you see it"
+)
+```
+
+此类型可以直接传递给 `send` 方法，它将自动包装在 `APNSwiftPayload` 中。
+
+### Payload
+
+`APNSwiftPayload` 是推送通知的元数据。诸如推送弹窗，徽章数之类的东西。[此处](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html)提供了每个属性的详细信息。它们遵循 Apple 文档中列出的一对一命名方案。
+
+```swift
+let alert = ...
+let aps = APNSwiftPayload(alert: alert, badge: 1, sound: .normal("cow.wav"))
+```
+
+这可以传递给 `send` 方法。
+
+### 自定义通知数据
+
+Apple 为工程师提供了为每个通知添加定制有效载荷数据的能力。为了方便操作，我们有了 `APNSwiftNotification`。
+
+```swift
+struct AcmeNotification: APNSwiftNotification {
+    let acme2: [String]
+    let aps: APNSwiftPayload
+
+    init(acme2: [String], aps: APNSwiftPayload) {
+        self.acme2 = acme2
+        self.aps = aps
+    }
+}
+
+let aps: APNSwiftPayload = ...
+let notification = AcmeNotification(acme2: ["bang", "whiz"], aps: aps)
+```
+
+可将此自定义通知类型传递给该 `send` 方法。
+
+## 更多信息
+
+了解更多可用方法的信息，请参阅 [APNSwift](https://github.com/kylebrowning/APNSwift)。
--- a/docs/advanced/server.zh.md
+++ b/docs/advanced/server.zh.md
@ -0,0 +1,233 @@
+# 服务器
+
+Vapor 包含一个基于 [SwiftNIO](https://github.com/apple/swift-nio) 构建的高性能异步 HTTP 服务器。该服务器支持 HTTP/1、HTTP/2 和协议升级，如 [WebSockets](websockets.zh.md)。服务器还支持启用 TLS (SSL)。
+
+## 配置
+
+Vapor 的默认 HTTP 服务器可以通过 `app.http.server` 来配置。
+
+```swift
+// 仅支持 HTTP/2
+app.http.server.configuration.supportVersions = [.two]
+```
+
+HTTP 服务器支持多种配置选项。
+
+### 主机名
+
+hostname 控制服务器将在哪个地址上接受新连接。默认地址为`127.0.0.1`。
+
+```swift
+// 配置自定义主机名
+app.http.server.configuration.hostname = "dev.local"
+```
+
+终端运行 `serve` 命令添加 `--hostname` (`-H`) 标志来修改服务器主机名或将 `hostname` 参数传递给 `app.server.start(...)` 来修改配置。
+
+```sh
+# 重写主机名配置
+vapor run serve --hostname dev.local
+```
+
+### 端口
+
+port 选项控制服务器将在指定地址上的哪个端口接受新连接。默认值为`8080`。
+
+```swift
+// 配置自定义端口。
+app.http.server.configuration.port = 1337
+```
+
+!!! 资料
+    绑定小于`1024`的端口可能需要 `sudo` 提权。不支持大于`65535`的端口。
+
+终端运行 `serve` 命令添加 `--port` (`-p`) 标志来修改服务器端口或将 `port` 参数传递给 `app.server.start(...)` 来修改配置。
+
+```sh
+# 重写端口配置
+vapor run serve --port 1337
+```
+
+### Backlog
+
+`backlog` 参数定义待处理连接队列的最大长度。默认值为`256`。
+
+```swift
+// 自定义积压队列长度
+app.http.server.configuration.backlog = 128
+```
+
+### 地址复用
+
+`reuseAddress` 参数允许重用本地地址。默认为 `true`。
+
+```swift
+// 禁用地址复用
+app.http.server.configuration.reuseAddress = false
+```
+
+### TCP 无延迟
+
+启用 `tcpNoDelay` 参数将尝试 TCP 数据包延迟最小化。默认为 `true`。
+
+```swift
+// 降低数据包延迟。
+app.http.server.configuration.tcpNoDelay = true
+```
+
+### 响应压缩
+
+`responseCompression` 参数使用 gzip 控制 HTTP 响应压缩。默认值为 `.disabled`。
+
+```swift
+// 启用 HTTP 响应压缩。
+app.http.server.configuration.responseCompression = .enabled
+```
+
+要指定初始缓冲区容量，请使用 `initialByteBufferCapacity` 参数。
+
+```swift
+.enabled(initialByteBufferCapacity: 1024)
+```
+
+### 请求解压
+
+`requestDecompression` 参数使用 gzip 控制 HTTP 请求解压。默认值为 `.disabled`。
+
+```swift
+// 启用 HTTP 请求解压
+app.http.server.configuration.requestDecompression = .enabled
+```
+
+要指定减压限制，请使用 `limit` 参数。默认值为 `.ratio(10)`。
+
+```swift
+// 无解压大小限制
+.enabled(limit: .none)
+```
+
+可用选项有：
+
+- `size`：以字节为单位的最大解压缩大小。
+- `ratio`：最大解压缩大小为压缩字节的比率。
+- `none`：没有大小限制。
+
+设置解压缩大小限制有助于防止恶意压缩的 HTTP 请求使用大量内存。
+
+### 管道
+
+`supportPipelining` 参数启用对 HTTP 请求和响应管道的支持。默认值为 `false`。
+
+```swift
+// 启用管道支持。
+app.http.server.configuration.supportPipelining = true
+```
+
+### 版本
+
+`supportVersions` 参数控制服务器使用的 HTTP 版本。默认情况下，启用 TLS 时，Vapor 将同时支持 HTTP/1 和 HTTP/2。禁用 TLS 时仅支持 HTTP/1。
+
+```swift
+// 禁用 HTTP/1 。
+app.http.server.configuration.supportVersions = [.two]
+```
+
+### TLS
+
+`tlsConfiguration` 参数控制是否在服务器上启用 TLS (SSL)。默认值为 `nil`。
+
+```swift
+// 启用 TLS.
+try app.http.server.configuration.tlsConfiguration = .forServer(
+    certificateChain: NIOSSLCertificate.fromPEMFile("/path/to/cert.pem").map { .certificate($0) },
+    privateKey: .file("/path/to/key.pem")
+)
+```
+
+要编译此配置，你需要在配置文件的顶部添加 `import NIOSSL` 导入包。你可能还需要在 Package.swift 文件中添加 NIOSSL 依赖项。
+
+### 名称
+
+`serverName` 参数控制 `Server` 传出 HTTP 响应的报头。默认值为 `nil`。
+
+```swift
+// 添加 'Server: vapor' 到响应头。
+app.http.server.configuration.serverName = "vapor"
+```
+
+## 服务命令
+
+要启动 Vapor 的服务器，请在终端使用 `serve` 命令。如果没有指定其他命令，该命令将默认运行。
+
+```swift
+vapor run serve
+```
+
+`serve` 命令接受以下参数：
+
+- `hostname` (`-H`)：重写主机名配置。
+- `port` (`-p`)：重写端口号配置。
+- `bind` (`-b`)：重写由`:`连接的主机名和端口号配置。
+
+下面是使用 `--bind` (`-b`) 标志的一个示例：
+
+```swift
+vapor run serve -b 0.0.0.0:80
+```
+
+使用 `vapor run serve --help` 以获取更多信息。
+
+`serve` 命令将侦听 `SIGTERM` 和 `SIGINT` 信号，以正常关闭服务器。使用 `ctrl+c` (`^c`) 发送 `SIGINT` 信号。当日志级别设置为 `debug` 或更低时，将记录有关安全关机状态的信息。
+
+## 手动启动
+
+Vapor 的服务器可以使用 `app.server` 手动启动。
+
+```swift
+// 启动 Vapor 服务器。
+try app.server.start()
+// 请求服务器关闭。
+app.server.shutdown()
+// 等待服务器关闭。
+try app.server.onShutdown.wait()
+```
+
+## 服务器
+
+Vapor 使用的服务器是可配置的。默认情况下，使用内置的 HTTP 服务器。
+
+```swift
+app.servers.use(.http)
+```
+
+### 自定义服务器
+
+Vapor 的默认 HTTP 服务器可以替换为任何遵循 `Server` 的服务器。
+
+```swift
+import Vapor
+
+final class MyServer: Server {
+	...
+}
+
+app.servers.use { app in
+	MyServer()
+}
+```
+
+自定义服务器可以扩展 `Application.Servers.Provider` 以使用点语法。
+
+```swift
+extension Application.Servers.Provider {
+    static var myServer: Self {
+        .init {
+            $0.servers.use { app in
+            	MyServer()
+            }
+        }
+    }
+}
+
+app.servers.use(.myServer)
+```