• 首页
  • 博客
  • 项目
  • 留言墙

微信公众号

喜欢我的内容的话不妨关注公众号获取最新动态 🫶

© 2025 • 5km • Fork 自cali.so

首页博客项目留言墙
总浏览量 5.9万最近访客来自 Ashburn, US🇺🇸
  • Fluent
  • IDE 配置
  • 安装 vscode
  • 安装 Swift 插件
  • 配置 Swift 插件
  • 配置代理
  • 新建项目
  • 项目调整
  • 添加代码
  • 添加 Acronym 数据模型
  • 添加模型迁移代码
  • 修改配置文件
  • 配置数据库
  • 数据库迁移
  • 添加路由
  • 模型 Codable & Decodable
  • 添加 Post 路由
  • 测试路由
  • 总结
  • 附件
Vapor 教程系列 - 01 创建项目和设置数据库与路由
2023/10/10Vapor Web 开发

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

本文我们正式开启 Vapor 的学习和实践之旅,跟着我一起构建一个 “Today I learned” 的应用,主要用来记录字母缩写和含义,是个非常简单的小应用,麻雀虽小五脏俱全,会用到 Vapor 常用的很多模块,能覆盖后面我们自己做应用的很多场景。

472次点击13分钟阅读

废话不多说我们开始吧!

  • 第一部分:构建 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。

相关文章

Vapor 教程系列 - 05 异步编程与全面错误处理

2024/11/16Vapor Web 开发977分钟阅读

Vapor 教程系列 - 04 Web API 测试与稳定性验证

2024/11/16Vapor Web 开发996分钟阅读

Vapor 教程系列 - 03 进阶数据库模型与 API 实现

2023/12/26Vapor Web 开发17327分钟阅读