Vapor 教程系列 - 01 创建项目和设置数据库与路由

废话不多说我们开始吧！

• 第一部分：构建 Web API
  • 创建项目和设置数据库与路由
  • 实现基本 CRUD 操作与控制器封装
  • 进阶数据库模型与 API 实现
  • Web API 测试与稳定性验证
  • 异步编程与全面错误处理
• 第二部分：制作简单的前端网页应用
• 第三部分：数据校验、用户验证和授权
• 第四部分：Vapor 的进阶使用
• 第五部分：生产部署

本文我们将一起配置 Swift 的开发环境，然后创建一个新的 Vapor 应用，进行简单的调整，然后构建基础的数据库模型，使用数据库写简单的路由进行测试。

Fluent

在开始之前简单介绍一下，Fluent 是服务于 Swift 的 ORM(Object Relational mapping，对象关系映射) 框架，它利用 Swift 的强类型特性为你的数据库操作提供简易使用的接口。使用 Fluent 的核心是创建用于表示数据库中数据结构的模型，然后通过这些模型来执行创建、读取、更新和删除等操作，而不必编写原始的 SQL 查询语句。

其中，Models 是我们基本的数据描述同时也可以用于 Fluent 与数据库交互。Models 是定义的一些对象，比如用户配置、应用配置等，这些都是我们要在数据库中访问和保存的。

IDE 配置

为了满足 macOS 和 Linux 的综合开发需求，决定后面我们都使用 vscode 作为 Swift 的开发环境，本文对于各系统下 Swift 安装不做过多赘述，可以参考这里进行安装，这里只说一下 vscode Swift 开发环境的搭建。

安装 vscode

vscode 官网 下载安装即可，如果不知如何安装，官网也有相应文档，或者查找网上相应教程即可。

• macOS 安装 Vscode
• Linux 安装 Vscode

安装 Swift 插件

找到侧边栏扩展，搜索 Swift 即可找到 Swift Server Work Group 开发的 Swift 插件，安装即可：

vscode 安装 Swift 插件

配置 Swift 插件

Swift 插件要用到 sourcekit-lsp ，所以需要为插件配置正确路径。

打开终端，获取 sourcekit-lsp 的路径（正常安装完了 swift 之后，都有这玩意儿）：我这里就是 /usr/bin/sourcekit-lsp，复制这个路径。

回到 vscode，按快捷键 ctrl+,（Linux 下） 或者 command+,调出设置界面，搜索框输入 swift，可以看到有 Swift 设置组下面有个 Sourcekit-LSP，点击，将刚才复制的 sourcekit-lsp 的路径粘贴进去，按回车键：

swift插件配置 sourcekit-lsp 路径

💡 Tip

其实，插件回到系统 Path 中找 sourcekit-lsp，自己配置上为了万无一失。这样插件应该就能使用了。

配置代理

Swift 插件使用 SPM 的方式管理项目，依赖包很多是 github 上的，进行依赖解析时需要拉取依赖，在国内会有一定网络问题（你懂的），所以可能还需要配置代理，大家配置自己的科学上网的代理（不要用我的，你得自己有代理才行），或者系统全局 Github 加速，Vscode 配置代理也是找到设置界面搜索 proxy，就在 http:Proxy 的内容框中填写自己的即可：

vscode 配置 proxy

至此，IDE 搭建好了后就去终端新建项目啦。

新建项目

终端中使用 vapor 工具中的 new 命令新建新的工程项目

💡 提示
正常情况下，vapor 会从 Github 拉去模板，但是在国内往往很慢或者直接出错，可能需要 Github 加速或者科学上网，具体怎么做自己网上了解吧。

可以在终端中指定使用代理，实现终端中命令网络的科学上网，我是这样做的:

过程中，选择使用 Fluent，然后选择使用 Vapor 推荐的 Postgresql 数据库，选择不使用 Leaf(前端页面内容渲染引擎)，整体的过程如图所示：

vapor新建项目

简单介绍一下文件结构

• Dockerfile 和 docker-compose.yml 是用于 docker 部署的配置文件
• Package.swift 是包配置文件，管理依赖和编译构建等配置
• Public 用于存放 web 托管的静态文件，比如 image、css、js、html 等
• Sources 就是存放我们 swift 源代码的目录
  • App 是主要存放我们编写的代码的路径，Vapor 采用 MVC 设计模式，所以会有 Models、Controllers 目录，另外 Migrations 目录用于存放 Fluent 数据库数据模型操作的定义用于数据库模型更新和回滚；另外 configure.swift 是进行项目配置的文件，包含各种中间件的配置等，routes.swift 写的是 API 路由。
  • 原来还有一个 Run 目录存放 main.swift 入口，现在改为 App 下的 entrypoint.swift 这个文件一般改动较少。
• Tests 目录下存放的是应用的测试代码

最好是先使用命令 swift run 构建一下，这样 vscode 就能自动加载获取的包解析结果了：

项目调整

下面需要对工程进行简单的调整，删除 Sources/App 下的一些默认文件，执行以下命令：

使用 vscode 打开我们的项目，后面操作就可以在 vscode 操作了，vscode 中也可以打开终端：

正常的话就能用 vscode 打开项目目录了。

vscode打开项目目录

💡 Tip

正常打开的话，vscode 会根据根目录下的 Package.swift 加载 Package，需要等一段时间才能进行智能 IDE 的操作。

打开 Sources/App/configure.swift 文件，删除 app.migrations.add(CreateTodo()):

删除数据库迁移代码

打开 Sources/App/routes.swift，删除try app.register(collection: TodoController()):

删除路由控制器注册代码

添加代码

添加 Acronym 数据模型

在 Sources/App/Models 下新建文件 Acronym.swift，内容如下：

代码注解：

• 定义 Acronym 模型类，遵循 Model 协议；
• 定义 schema ，这是每个模型都应该有的 let 而且是静态常量，这个名称对应的就是数据库中表名，一般使用 Snake 命名方式，在 Swift 代码中类名、变量名、方法名一般采用驼峰命名法，需要注意一下这个规范；
• 每个模型都应该有个用于查询数据的字段，对应定义名为 id，这个变量为 Optional 的 UUID 类型可以为空，同时使用 ID 装饰器，指定 key 为 id 类型；
• 接着定义了两个 Field 对应到数据库表中的字段，使用 Field 装饰器指定 key 为表中字段名，如果变量是可选的，需要使用 OptionField 装饰器；
• 必须包含两个初始化方法，一个是空的模型初始化实现，用于数据库检索数据时初始化模型数据用，另一个初始化实现用于创建模型数据，这是必须的。

添加模型迁移代码

在 Sources/App/Migrations 下新建文件 CreateAcronym.swift，内容如下：

代码注释：

• 定义 CreateAcronym 结构体，遵循 AsyncMigration 协议；
• 协议中规定必须实现 prepare 和 revert 方法，分别用于创建数据表和删除数据表；

迁移操作只会执行一次，一旦在数据库中创建数据库表就不会再执行。

修改配置文件

编辑 Sources/App/configure.swift 文件，在 try routes(app) 上面添加以下代码：

配置数据库

如果你的系统中没有安装 Postgresql 数据库，建议使用 docker 启动 Postgresql 数据库，可以执行以下命令，前提是你已经安装了 Docker：

上面数据库安装好了之后，对应数据库的信息为：

• host: localhost
• port: 5432
• user: vapor_username
• password: vapor_password
• database: postgres

我们看一下 Sources/App/configure.swift 文件中的数据库配置：

可以看到默认从环境变量中加载配置，如果没有相应的环境变量就采用默认值，而这些默认值正好对应的就是 docker 运行 Postgresql 数据库的对应信息。这样就可以继续后面的操作了，可以忽略下面内容，直接跳到下一小节。

当然，如果你有自己安装好的 Postgresql 数据库，可以添加环境变量文件，比如我在另外一台机器上配置了数据库，对应信息如下：

• host: 192.168.31.74
• port: 5432
• user: pi
• password: ······
• database: tilapp

👆上面的信息需要根据自身的情况调整。
👨‍💻 macOS 中可以使用 orbstack 或者 Docker Desktop 通过 Postgresql 镜像轻松搭建数据库💡

在 TILApp 根目录下新建 .env 文件，内容如下：

数据库迁移

这里建议使用 Vapor 命令工具进行数据库迁移：

命令执行过程中会出现提示要不要继续创建数据表，输入 y 继续即可！成功后就创建好了数据库表，整个过程显示如下：

💡 提示
可能会出现数据库连接或用户权限问题，这个大概率是上面 .env 中配置的环境变量有问题，请仔细检查确定指定的用户有权限操作指定的数据库。

添加路由

下面添加一个 Post 路由测试模型的保存。

模型 Codable & Decodable

使创建的模型遵循 Content 协议，打开 Sources/App/Models/Acronym.swift 文件，在末尾添加以下代码：

这样就能从以下的 Json 数据中反序列化到模型数据：

添加 Post 路由

编辑 Sources/App/routes.swift 文件，在 routes 函数中的 /api/acronyms 路由上注册新的路由，用来处理 Post 请求：

代码注释：

• 解析请求中的 json 数据，生成 acronym 模型数据；
• 尝试执行模型数据的 save 方法保存数据到数据库，期间会自动生成 id，最后返回传入的数据。

vscode 打开工程的时候就会自动生成调试运行的配置，可以通过 vscode 的调试运行应用：

vscode调试项目

1. 点击侧边栏调试按钮；
2. 点击调试按钮；
3. 成功运行后会显示如图位置 3 的工具栏；
4. 应用运行在 http:127.0.0.1:8080

浏览器打开网址就能看到 It works!

测试路由

可以使用多种 API 测试工具测试新增的路由，既然我们使用 vscode 了那就用支持 vscode 插件的测试工具得了，这里推荐使用 RapidAPI Client，可以在 Vscode 中搜索安装，然后如下图使用 RapidAPI 测试新增的 Post 路由：

RapidAPI Client测试接口

按照图中序号说明操作：

1. 安装完 RapidAPI 扩展，就会在界面侧边栏显示 RapidAPI 工具按钮，点击侧边栏按钮；
2. 点击默认生成的一个接口测试；
3. 选中请求方法为 Post；
4. 将接口地址填入地址栏；
5. 单击 body；
6. 单击 JOSN；
7. 输入请求体 json 数据：

点击发送按钮。正常的话就能看到右侧显示响应 200 OK和具体响应时间，同时能看到响应数据为生成的数据库数据，包含了 id：

总结

🎉 至此，我们配置好了开发环境，并新建了项目，然后完成了数据库的配置和数据模型代码的编写，最后实现了基本的 API 路由并进行了初步测试，整个过程还涉及了数据库、Docker 使用等其它知识，自行做初步了解就能搞定🚀！希望本文能给你带来帮助，下篇文章见！🔥

附件

本文最终代码 s1-1.zip。