构建 Web API 1- 搭建 IDE 新建项目并构建数据库及路由代码
本文我们正式开启 Vapor 的学习和实践之旅,跟着我一起构建一个 “Today I learned” 的应用,主要用来记录字母缩写和含义,是个非常简单的小应用,麻雀虽小五脏俱全,会用到 Vapor 常用的很多模块,能覆盖后面我们自己做应用的很多场景。
废话不多说我们开始吧!
- 第一部分:构建 Web API
- 搭建 IDE 新建项目并构建数据库及路由代码
- ...
- 第二部分:制作简单的前端网页应用
- 第三部分:数据校验、用户验证和授权
- 第四部分: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 官网 下载安装即可,如果不知如何安装,官网也有相应文档,或者查找网上相应教程即可。
安装 Swift 插件
找到侧边栏扩展,搜索 Swift 即可找到 Swift Server Work Group 开发的 Swift 插件,安装即可:
配置 Swift 插件
Swift 插件要用到 sourcekit-lsp ,所以需要为插件配置正确路径。
打开终端,获取 sourcekit-lsp 的路径(正常安装完了 swift 之后,都有这玩意儿):我这里就是 /usr/bin/sourcekit-lsp
,复制这个路径。
回到 vscode,按快捷键 ctrl
+,
(Linux 下) 或者 command
+,
调出设置界面,搜索框输入 swift,可以看到有 Swift 设置组下面有个 Sourcekit-LSP,点击,将刚才复制的 sourcekit-lsp 的路径粘贴进去,按回车键:
💡 Tip
其实,插件回到系统 Path 中找 sourcekit-lsp,自己配置上为了万无一失。这样插件应该就能使用了。
配置代理
Swift 插件使用 SPM 的方式管理项目,依赖包很多是 github 上的,进行依赖解析时需要拉取依赖,在国内会有一定网络问题(你懂的),所以可能还需要配置代理,大家配置自己的科学上网的代理(不要用我的,你得自己有代理才行),或者系统全局 Github 加速,Vscode 配置代理也是找到设置界面搜索 proxy,就在 http:Proxy 的内容框中填写自己的即可:
至此,IDE 搭建好了后就去终端新建项目啦。
新建项目
终端中使用 vapor 工具中的 new 命令新建新的工程项目
💡 提示
正常情况下,vapor 会从 Github 拉去模板,但是在国内往往很慢或者直接出错,可能需要 Github 加速或者科学上网,具体怎么做自己网上了解吧。
可以在终端中指定使用代理,实现终端中命令网络的科学上网,我是这样做的:
过程中,选择使用 Fluent,然后选择使用 Vapor 推荐的 Postgresql 数据库,选择不使用 Leaf(前端页面内容渲染引擎),整体的过程如图所示:
简单介绍一下文件结构
- 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 打开项目目录了。
💡 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 的调试运行应用:
- 点击侧边栏调试按钮;
- 点击调试按钮;
- 成功运行后会显示如图位置 3 的工具栏;
- 应用运行在
http:127.0.0.1:8080
浏览器打开网址就能看到 It works!
测试路由
可以使用多种 API 测试工具测试新增的路由,既然我们使用 vscode 了那就用支持 vscode 插件的测试工具得了,这里推荐使用 RapidAPI Client,可以在 Vscode 中搜索安装,然后如下图使用 RapidAPI 测试新增的 Post 路由:
按照图中序号说明操作:
- 安装完 RapidAPI 扩展,就会在界面侧边栏显示 RapidAPI 工具按钮,点击侧边栏按钮;
- 点击默认生成的一个接口测试;
- 选中请求方法为 Post;
- 将接口地址填入地址栏;
- 单击 body;
- 单击 JOSN;
- 输入请求体 json 数据:
点击发送按钮。正常的话就能看到右侧显示响应 200 OK和具体响应时间,同时能看到响应数据为生成的数据库数据,包含了 id:
总结
🎉 至此,我们配置好了开发环境,并新建了项目,然后完成了数据库的配置和数据模型代码的编写,最后实现了基本的 API 路由并进行了初步测试,整个过程还涉及了数据库、Docker 使用等其它知识,自行做初步了解就能搞定🚀!希望本文能给你带来帮助,下篇文章见!🔥
附件
本文最终代码 s1-1.zip。