diff --git a/docs/getting-started/folder-structure.zh.md b/docs/getting-started/folder-structure.zh.md index e1d8eae9..fad73925 100644 --- a/docs/getting-started/folder-structure.zh.md +++ b/docs/getting-started/folder-structure.zh.md @@ -1,8 +1,6 @@ # 项目结构 -现在，你已经创建并运行了第一个 Vapor 应用程序，让我们稍微花点时间熟悉一下 Vapor 的项目结构。 - -该结构是在 [SPM](spm.md) 的基础上演化而来；因此，如果你曾经使用过 SPM，应该会很熟悉。 +现在，你已经创建并运行了第一个 Vapor 应用程序，让我们稍微花点时间熟悉一下 Vapor 的项目结构。该结构是在 [SPM](spm.zh.md) 的基础上演化而来；因此，如果你曾经使用过 SPM，应该会很熟悉。 ``` @@ -27,9 +25,7 @@ ## Public -如果你使用了 `FileMiddleware` 中间件，那么此文件夹包含你的应用程序提供的所有公共文件，通常是图片、`.css`样式和浏览器脚本等。 - -例如，对 `localhost:8080/favicon.ico` 发起的请求将检查是否存在 `Public/favicon.ico` 图片并回应。 +如果你使用了 `FileMiddleware` 中间件，那么此文件夹包含你的应用程序提供的所有公共文件，通常是图片、`.css` 样式和浏览器脚本等。 例如，对 `localhost:8080/favicon.ico` 发起的请求将检查是否存在 `Public/favicon.ico` 图片并回应。 在 Vapor 可以提供公共文件之前，你需要在 `configure.swift` 文件中启用`FileMiddleware`，参考如下所示： @@ -43,7 +39,7 @@ app.middleware.use(fileMiddleware) ## Sources -该文件夹包含项目的所有 Swift 代码源文件。文件夹 `App`和 `Run`反应软件包的模块，例如这篇 [SPM](spm.md) 文章中所述。 +该文件夹包含项目的所有 Swift 代码源文件。文件夹 `App` 和 `Run` 反应软件包的模块，例如这篇 [SPM](spm.zh.md) 文章中所述。 ### App @@ -73,12 +69,13 @@ models 文件夹常用于存放 `Content` 和 Fluent `Model` 的类或结构体 这是主要的可执行目标，只包含启动和运行应用程序所需的代码。 +#### main.swift + +这个文件创建并运行一个配置好的 `Application` 实例。 + ## Tests - `Sources` 文件夹中的每个不可运行的模块在 `Tests` 中都可以创建一个对应的文件夹，包含 `XCTest` 模块上构建的用例，用来测试你的代码。 - - 可以在命令行使用 `swift test`或在 Xcode 中按 `⌘+U` 来进行测试。 - +`Sources` 文件夹中的每个不可运行的模块在 `Tests` 中都可以创建一个对应的文件夹，包含 `XCTest` 模块上构建的用例，用来测试你的代码。可以在命令行使用 `swift test`或在 Xcode 中按 `⌘+U` 来进行测试。 ### AppTests @@ -86,5 +83,6 @@ models 文件夹常用于存放 `Content` 和 Fluent `Model` 的类或结构体 ## Package.swift -最后，是这个项目运行所依赖的第三方库配置。 +最后是 [SPM](spm.zh.md) 文件，是这个项目运行所依赖的第三方库配置。 + diff --git a/docs/getting-started/hello-world.zh.md b/docs/getting-started/hello-world.zh.md index d0979fc7..8494052e 100644 --- a/docs/getting-started/hello-world.zh.md +++ b/docs/getting-started/hello-world.zh.md @@ -5,14 +5,12 @@ 如果尚未安装 Swift 和 Vapor Toolbox，请查看安装部分。 -- [安装 → macOS](../install/macos.md) -- [安装 → Linux](../install/linux.md) +- [安装 → macOS](../install/macos.md) +- [安装 → Linux](../install/linux.md) ## 创建 -首先，在电脑上创建 Vapor 项目。 - -打开终端并使用以下 Toolbox 的命令行，这将会在当前目录创建一个包含 Vapor 项目的文件夹。 +首先，在电脑上创建 Vapor 项目。打开终端并使用以下 Toolbox 的命令行，这将会在当前目录创建一个包含 Vapor 项目的文件夹。 ```sh vapor new hello -n @@ -21,6 +19,8 @@ vapor new hello -n !!! tip "建议" 使用 `-n` 为所有的问题自动选择 no 来为您提供一个基本的模板。 +!!! tip "建议" + Vapor 以及自带的模板默认使用 `async`/`await`。如果你的系统不能更新到 macOS 12 或者想继续使用 `EventLoopFuture`。运行命令时可以添加此标志 `--branch macos10-15`。 命令完成后，切换到新创建的文件夹 @@ -39,11 +39,11 @@ open Package.swift ``` -Xcode 将自动开始下载Swift包管理器依赖，在第一次打开一个项目时，这可能需要一些时间，当依赖下载后，Xcode将显示可以用的 Scheme。 +Xcode 将自动开始下载 Swift 包管理器依赖，在第一次打开一个项目时，这可能需要一些时间，当依赖下载后，Xcode 将显示可以用的 Scheme。 -在窗口的顶部，在Play和Stop按钮的右侧，单击项目名称以选择项目的Scheme，并选择一个适当的target——大概率是“My Mac”。单击play按钮编译并运行项目。 +在窗口的顶部，在 Play 和 Stop 按钮的右侧，单击项目名称以选择项目的 Scheme，并选择一个适当的 target ——大概率是 “My Mac”。单击 play 按钮编译并运行项目。 -你应该会在Xcode窗口的底部看到控制台弹出。 +你应该会在 Xcode 窗口的底部看到控制台输出以下信息。 ```sh [ INFO ] Server starting on http://127.0.0.1:8080 @@ -51,7 +51,7 @@ Xcode 将自动开始下载Swift包管理器依赖，在第一次打开一个项 ### Linux -在 Linux 和其他操作系统上(甚至在 macOS 上如果你不想使用 Xcode )，你可以在你喜欢的编辑器中编辑项目，比如 Vim 或 VSCode 。关于设置其他ide的最新细节，请参阅 [Swift Server Guides](https://github.com/swift-server/guides/blob/main/docs/setup-and-ide-alternatives.md)。 +在 Linux 和其他操作系统上（甚至在 macOS 上如果你不想使用 Xcode），你可以在你喜欢的编辑器中编辑项目，比如 Vim 或 VSCode 。关于设置其他 IDE 的最新细节，请参阅 [Swift Server Guides](https://github.com/swift-server/guides/blob/main/docs/setup-and-ide-alternatives.md)。 在终端运行以下命令来编译和运行你的项目。 @@ -64,7 +64,7 @@ swift run [ INFO ] Server starting on http://127.0.0.1:8080 ``` -## Visit Localhost +## 访问 Localhost 打开你的浏览器，然后访问 localhost:8080/hello 或者 http://127.0.0.1:8080 diff --git a/docs/getting-started/spm.zh.md b/docs/getting-started/spm.zh.md index 96864150..cbbdb9a5 100644 --- a/docs/getting-started/spm.zh.md +++ b/docs/getting-started/spm.zh.md @@ -1,8 +1,8 @@ # Swift Package Manager -[Swift Package Manager](https://swift.org/package-manager/)(SPM)用于构建项目的源代码和依赖项。由于 Vapor 严重依赖 SPM，因此最好了解其工作原理。 +[Swift Package Manager](https://swift.org/package-manager/)(SPM) 用于构建项目的源代码和依赖项。由于 Vapor 严重依赖 SPM，因此最好了解其工作原理。 -SPM 与 Cocoapods，Ruby gems 和 NPM 相似。您可以在命令行中将 SPM 与 `swift build`、`swift test` 等命令或兼容的 IDE 结合使用。但是，与其他软件包管理器不同，SPM 软件包没有中央软件包索引。SPM 使用 [Git 标签](https://git-scm.com/book/en/v2/Git-Basics-Tagging) 和 URL 来获取 Git 存储库和依赖版本。 +SPM 与 Cocoapods，Ruby gems 和 NPM 相似。你可以在命令行中将 SPM 与 `swift build`、`swift test` 等命令或兼容的 IDE 结合使用。但是，与其他软件包管理器不同，SPM 软件包没有中央软件包索引。SPM 使用 [Git 标签](https://git-scm.com/book/en/v2/Git-Basics-Tagging) 和 URL 来获取 Git 存储库和依赖版本。 ## Package Manifest @@ -39,7 +39,7 @@ let package = Package( ### Tools Version -第一行表示需要使用的 Swift tools 版本号，它指明了 Swift 的最低可用版本。Package 描述 API 可能随着 Swift 版本而改变，所以这一行将让 Swift 确认怎么取解析你的配置文件。 +第一行表示需要使用的 Swift tools 版本号，它指明了 Swift 的最低可用版本。Package 描述 API 可能随着 Swift 版本而改变，所以这一行将让 Swift 确认怎么去解析你的配置文件。 ### Package Name @@ -47,15 +47,15 @@ let package = Package( ### Platforms -`platforms` 数组指定此程序包支持的平台和版本。通过指定 `.macOS（.v10_14）`，说明此软件包需要 macOS Mojave 或更高版本。 Xcode 加载该项目时，它将最低部署版本设置为 10.14，以便您可以使用所有可用的 API。 +`platforms` 数组指定此程序包支持的平台和版本。通过指定 `.macOS（.v10_14）`，说明此软件包需要 macOS Mojave 或更高版本。 Xcode 加载该项目时，它将最低部署版本设置为 10.14，以便你可以使用所有可用的 API。 ### Products -products 字段代表 package 构建的时候要生成的 targets。示例中，有两个 target，一个是 `library`，另一个是 `executable`。 +products 字段代表 package 构建的时候要生成的 targets。示例中，有两个 target，一个是库，另一个是可执行文件。 ### Dependencies -dependencies 字段代表项目需要依赖的 package。所有 Vapor 应用都依赖 Vapor package ，但是你也可以添加其它想要的 dependency。 +dependencies 字段代表项目需要依赖的 package。所有 Vapor 应用都依赖 Vapor package ，但是你也可以添加其它想要的依赖库。 如上面这个示例，[vapor/vapor](https://github.com/vapor/vapor) 4.0 或以上版本是这个 package 的 dependency。当在 package 中添加了 dependency 后，接下来你必须设置是哪个 targets 依赖了新的可用模块。 @@ -64,9 +64,9 @@ dependencies 字段代表项目需要依赖的 package。所有 Vapor 应用都 Targets 是你的 package 里包含 modules、executables 以及 tests 总和。虽然可以添加任意多的 targets 来组织代码，但大部分 Vapor 应用有 3 个 target 就足够了。每个 target 声明了它依赖的 module。为了在代码中可以 import 这些 modules ，你必须在这里添加 module 名字。一个 target 可以依赖于工程中其它的 target 或者任意你添加在 [dependencies](#dependencies) 数组中且暴露出来的 modules。 !!! tip "建议" - 可运行 targets (包含 `main.swift` 文件的 target) 不能被其它 modules 导入。这就是为什么 Vapor 会有 `App` 和 `Run` 两种 target。任何包含在 App 中的代码都可以在 `AppTests` 中被测试验证。 + 可运行 targets（包含 `main.swift` 文件的 target）不能被其它 modules 导入。这就是为什么 Vapor 会有 `App` 和 `Run` 两种 target。任何包含在 App 中的代码都可以在 `AppTests` 中被测试验证。 -## Folder Structure +## 目录结构 以下是典型的 SPM package 目录结构。 @@ -87,7 +87,7 @@ Targets 是你的 package 里包含 modules、executables 以及 tests 总和。 ## Package.resolved -第一次构建成功后，SPM 将会自动创建一个 `Package.resolved` 文件。`Package.resolved` 保存了当前项目所有用到的 `dependency` 版本。下一次当你构建你的项目时将会同样的版本，甚至是这些依赖有更新的版本也不会也使用更新的版本。 +第一次构建成功后，SPM 将会自动创建一个 `Package.resolved` 文件。`Package.resolved` 保存了当前项目所有用到的依赖库版本。下一次当你构建你的项目时将会同样的版本，甚至是这些依赖有更新的版本时也不会使用。 更新依赖, 运行 `swift package update`. @@ -97,4 +97,4 @@ Targets 是你的 package 里包含 modules、executables 以及 tests 总和。 如果要更新到最新的依赖项，请使用 File → Swift Packages → 更新到最新的 Swift Package 版本。 -您可能还想将 `.swiftpm` 文件添加到您的 `.gitignore` 文件中（Xcode 在此处存储 Xcode 项目配置）。 +你可能还想将 `.swiftpm` 文件添加到你的 `.gitignore` 文件中（Xcode 在此处存储 Xcode 项目配置）。 diff --git a/docs/getting-started/xcode.zh.md b/docs/getting-started/xcode.zh.md index d3d7c7c3..855942f5 100644 --- a/docs/getting-started/xcode.zh.md +++ b/docs/getting-started/xcode.zh.md @@ -1,18 +1,18 @@ # Xcode -这页将显示一下使用Xcode的提示和技巧。如果你使用不同的开发环境，你可以跳过此页。 +这篇将介绍一些使用 Xcode 的提示和技巧。如果你使用不同的开发环境，你可以跳过此篇。 ## 自定义工作目录(Working directory) -Xcode 将默认在 _DerivedData_ 目录运行项目。这与项目的根目录(你的 _Package.swift_ 文件所在的目录)不在同一个目录，这意味着 Vapor 将找不到像 _.env_ 或者 _Public_ 等一些文件和目录。 +Xcode 将默认在 _DerivedData_ 目录运行项目。这与项目的根目录（你的 _Package.swift_ 文件所在的目录）不在同一个目录，这意味着 Vapor 将找不到像 _.env_ 或者 _Public_ 等一些文件和目录。 -如果在运行应用程序时看到以下警告，您就可以知道这正在发生。 +如果在运行应用程序时看到以下警告，你就可以知道这正在发生。 ```fish [ WARNING ] No custom working directory set for this scheme, using /path/to/DerivedData/project-abcdef/Build/ ``` -要解决这个问题，你可以在 Xcode schem 中为你的项目设置一个自定义的工作目录。 +要解决这个问题，你可以在 Xcode scheme 中为你的项目设置一个自定义的工作目录。 首先，编辑项目的 scheme。 @@ -22,16 +22,16 @@ Xcode 将默认在 _DerivedData_ 目录运行项目。这与项目的根目录( ![Xcode Scheme Menu](../images/xcode-scheme-menu.png) -在 scheme 编辑器中，选择 _Run_ action 以及 _Options_ tab页。选中 _Use custom working directory_ 然后输入你项目根目录。 +在 scheme 编辑器中，选择 _Run_ action 以及 _Options_ tab 页。选中 _Use custom working directory_ 然后输入你项目根目录。 ![Xcode Scheme Options](../images/xcode-scheme-options.png) -你可以在终端中运行 `pwd` 来获取你项目根目录的绝对目录 +你可以在终端中运行 `pwd` 来获取你项目根目录的绝对目录。 ```fish # 确认我们在 vapor 项目目录 vapor --version -# get path to this folder +# 获取当前目录的路径 pwd ```