atest v0.0.18 HTTP API Mock 实战：一条命令搞定前后端联调假接口

最近在调一个前后端分离的项目后端接口还没就绪前端同事天天催我给他一个能用的接口。以前我都是临时起一个 json-server或者干脆在代码里写死返回数据但每次都要单独配 CORS、做动态参数麻烦得很。后来我把 atest 升级到 v0.0.18发现它新增的 HTTP API Mock 功能正好能解决这个场景用 YAML 写好接口定义一条命令就能起一个本地 mock 服务。如果你也经常处理前后端联调、自动化测试、Demo 演示这类需要“假接口”的活儿这篇文章应该对你有用。我打算从 atest 这个工具本身聊起再一步步拆解 v0.0.18 里 HTTP API Mock 的配置方式、实操过程和常见坑尽量做到你照着抄就能用。1. atest 与 HTTP API Mock 的能力定位1.1 为什么要用 atest 做 Mock先说清楚 atest 是什么。它是一个开源的 API 自动化测试工具用 Go 写的发布物就是单个可执行文件没运行时依赖下载下来就能跑。和 Postman、JMeter 这类重量级工具相比它最大的特点是“命令友好”所有操作都能通过命令行完成可以很自然地嵌到 CI/CD 流程里。v0.0.18 之前atest 主要解决的是“接口测试用例怎么定义、怎么跑”的问题。你写一个 YAML 文件声明请求地址、方法、参数、预期响应它就能帮你把测试跑起来。到了 v0.0.18新增的 HTTP API Mock 功能相当于在同一套语法里加了一个“反向”能力不主动发请求而是起一个服务等着别人来请求然后按照你预先定义的规则返回结果。这个能力对日常开发有很直接的帮助前端和后端可以并行开发。后端接口没写好前端先按接口文档联调mock 服务顶上。自动化测试跑得更稳定。测试环境不稳定时用 mock 把第三方接口固定下来不会因为对方返回波动导致用例失败。做演示和培训很省事。只要带一个配置文件和二进制文件就能在任意机器上快速模拟一套后端服务。1.2 和常见 Mock 方案对比很多人第一反应可能是我又不是没有 mock 工具为什么要用 atest确实市面上能 mock HTTP 接口的工具不少我把常用的几个拉出来对比一下。方案优点缺点json-server上手快一个 JSON 文件就能出 RESTful 接口动态逻辑弱复杂校验基本要写 JS 扩展Mock.js前端拦截请求生成随机数据很方便只能在浏览器环境拦截模拟不了真实网络请求WireMock功能强大支持录制回放、动态响应Java 生态配置学习成本高启动较慢Postman Mock Server和 Postman 集合联动方便有云端版本本地请求转发有限制免费额度有要求atest v0.0.18 Mock命令行原生支持单文件部署和 atest 用例语法统一相对年轻生态没前面几个成熟表格里看不出来的是atest 的 mock 功能和它的测试用例定义是同一套配置思路。你在 mock 阶段写的接口描述后端真正写好之后稍作修改就能变成正式的 API 测试用例。这个“平滑过渡”的属性对我来说是最大的加分项。2. 安装与环境准备2.1 各平台安装方式atest 本身是个命令行工具所以安装非常简单。只要你的机器能跑 Go 编译出来的二进制文件基本不会有坑。如果你本机装了 Go可以直接通过go install安装指定版本go install github.com/LinuxSuRen/atestv0.0.18装完之后二进制会放在$GOPATH/bin或$HOME/go/bin目录下记得把这个目录加到 PATH 环境变量里。如果你不想装 Go就去 GitHub Releases 页面下载对应平台的压缩包。macOS 和 Linux 下载 tar.gz 或者直接下载可执行文件Windows 用户下载 zip 压缩包解压后把atest.exe所在目录加入 PATH 即可。热搜里提到的platform tools latest windows.zip我猜你是在搜相关工具包其实 atest 的 Windows 发行包命名也有类似风格以atest_Windows_xxx.zip为主解压就能用不需要额外安装依赖。2.2 验证安装是否成功装完之后打开终端执行下面命令确认版本atest version正常会输出类似atest version v0.0.18的信息。如果提示找不到命令先检查 PATH 有没有配好。Windows 下还可以直接在命令行输入where atest确认解析到的是不是刚刚解压的路径。验证完版本再看一下 mock 子命令是否可用atest mock --help如果能看到 mock 的启动参数说明说明当前发行版已经包含 HTTP API Mock 模块。这里多说一句部分早期版本可能没有 mock 功能看到下面的报错不要慌unknown command mock for atest这种情况一般是版本不对确认一下你用的是不是 v0.0.18 或更新的版本。3. Mock 功能核心配置与实操3.1 快速启动一个 Mock 服务atest mock 的启动逻辑很简单不写任何配置文件也能起一个空服务atest mock --port 8080执行后终端会进入监听状态默认监听本机 8080 端口。这时候你在另一个终端用 curl 访问一下curl http://localhost:8080/health虽然这个请求没有匹配到任何接口定义但服务本身能通。这样做的意义在于你可以先用一条命令验证环境再逐步把接口配置加进去。实际使用中我基本都会指定一个配置文件启动atest mock --port 8080 --file ./mock.yaml--file参数可以重复使用需要 mock 多个业务模块时拆成多个 YAML 文件再同时加载比写在一个巨型文件里好维护得多。这一点后面实战部分会再展开。3.2 编写第一个 Mock 定义文件Mock 配置文件的格式和 atest 测试用例的格式一脉相承核心是request和response的对应关系。下面是一个最简单的例子mock: - request: method: GET path: /hello response: status: 200 body: | {message: hello world}把这段内容保存为mock.yaml然后执行atest mock --port 8080 --file mock.yaml再开一个终端请求curl -i http://localhost:8080/hello返回内容应该是HTTP/1.1 200 OK Content-Type: text/plain {message: hello world}这个最简单的例子涉及三个关键点我分别说一下。第一request.method必须大写。写小写get有可能匹配不上因为 http 请求方法本身就是大写。第二request.path必须以/开头不能省略斜杠这是避免路径匹配歧义的基本约定。第三response.body建议用|块状字符串语法这样写 JSON 不用考虑转义格式也更清晰。3.3 支持状态码与响应头配置真实项目里一个接口不可能永远返回 200总得有 404、500 之类的异常分支。atest 的 mock 定义里response下面可以指定status和headers字段mock: - request: method: GET path: /api/users/10086 response: status: 404 headers: Content-Type: application/json body: | {code: 404, message: user not found}请求这个路径时就能拿到一个标准的 404 响应。headers字段可以灵活设置需要跨域时你可以在每个接口的响应里加上headers: Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Content-Type, Authorization这样前端在开发环境直接请求 mock 服务就不会被浏览器拦截了。不过要注意如果给每个接口手工加 CORS 头会显得很啰嗦。我建议把公共响应头抽出来先在配置文件顶层定义公共部分再在具体接口的 response 里覆盖具体语法以你使用的 atest 版本帮助为准思路是一致的。3.4 处理查询参数与路径参数接口文档里最常见的动态参数有两种一种在 URL 后面以?开头叫查询参数一种嵌在路径中间叫路径参数。两者在 atest mock 里都支持。查询参数的匹配方式是这样的mock: - request: method: GET path: /api/users query: page: 1 size: 20 response: status: 200 body: | {data: [], page: 1, size: 20}这里有个容易踩的坑query里的值要写成字符串。HTTP 协议里 URL 查询参数本身就是字符串形态如果你在 YAML 里写page: 1工具解析时可能会自动给你转成整数再去匹配请求里的字符串1两边对不上就匹配失败了。我习惯统一加引号省得 YAML 做类型推导。路径参数的写法稍微不同一般用冒号或者大括号占位我测试过 atest 常见的用法是在path里直接写占位符mock: - request: method: GET path: /api/users/:id response: status: 200 body: | {id: 1, name: Tom}这样请求/api/users/123和/api/users/999都会匹配到同一个 mock 规则。如果你的接口需要根据不同的 id 返回不同数据那就需要后续更灵活的配置或者干脆为每个关键 id 单独写一条规则把精确匹配的规则放前面带占位符的规则放后面。3.5 如何实现动态返回数据纯静态的返回数据很快会不够用。比如你想模拟一个分页接口页数不同返回的列表内容应该不一样或者你想模拟创建用户的接口希望每次返回的id都不重复。这里我建议你先跑一遍atest mock --help看一下当前版本的帮助说明里有没有模板变量或表达式相关的参数。这些功能在不同版本里可能叫法不一样比较常见的设计是支持在body里嵌入占位符例如response: status: 200 body: | {id: ${randomId}, name: user_${timestamp}}如果工具内置了这种模板解析启动之后每次请求返回的内容都会不同。如果你用的版本不支持模板变量也有一个土办法根据请求参数分流。比如把查询参数里的page1和page2分别写成两条不同的 mock 规则返回不同列表。虽然不够“智能”但胜在配置简单、不依赖额外功能应付联调足够了。4. 实战演练模拟一个完整的用户管理 API4.1 场景设计与接口清单光说概念容易飘我拿一个实际的用户管理模块来走一遍完整流程。假设前端需要以下五个接口方法路径说明GET/api/users?page1size20分页查询用户列表GET/api/users/1查询用户详情POST/api/users新建用户PUT/api/users/1更新用户信息DELETE/api/users/1删除用户在开始写配置之前我先确定一个目标前端所有请求都能得到合理的 JSON 返回并且查询分页、详情、新增、修改、删除五种行为都有对应的响应状态码。至于返回的数据具体长什么样作为 mock 阶段不需要和后端完全一致只要结构对齐就行这也是 mock 的价值所在——用最小的成本先把联调链路跑通。4.2 编写完整的 Mock 配置文件下面是这个场景的完整配置我拆成了几个文件按模块分开这里先演示一个文件里写多个接口的写法mock: - request: method: GET path: /api/users query: page: 1 size: 20 response: status: 200 headers: Content-Type: application/json body: | { code: 0, data: { list: [ {id: 1, name: Tom, email: tomexample.com}, {id: 2, name: Jerry, email: jerryexample.com} ], total: 2, page: 1, size: 20 } } - request: method: GET path: /api/users/1 response: status: 200 headers: Content-Type: application/json body: | { code: 0, data: { id: 1, name: Tom, email: tomexample.com, role: admin } } - request: method: POST path: /api/users response: status: 201 headers: Content-Type: application/json body: | { code: 0, data: { id: 100, name: new user, email: newexample.com } } - request: method: PUT path: /api/users/1 response: status: 200 headers: Content-Type: application/json body: | { code: 0, data: { id: 1, name: Tom Updated } } - request: method: DELETE path: /api/users/1 response: status: 204 headers: Content-Type: application/json body: 把文件保存为user-mock.yaml然后启动atest mock --port 8080 --file user-mock.yaml4.3 用 curl 验证 Mock 接口服务启动后我习惯逐个接口验证一遍避免前端联调时突然发现某个规则写错了。先验证列表接口curl -s http://localhost:8080/api/users?page1size20能返回 JSON 数组说明基本规则没问题。再验证一下查询参数不匹配的情况curl -s http://localhost:8080/api/users?page2size20这个请求如果没有命中任何规则不同版本的 atest 可能有不同处理逻辑。有的版本会直接返回 404有的版本会返回一个默认提示。这里我建议你看一下终端里 atest 输出的请求日志日志里会显示实际请求的路径和方法方便你判断是匹配规则的问题还是配置文件没加载的问题。验证详情接口curl -s http://localhost:8080/api/users/1验证新增、修改、删除接口curl -s -X POST http://localhost:8080/api/users curl -s -X PUT http://localhost:8080/api/users/1 curl -s -X DELETE http://localhost:8080/api/users/1 -o /dev/null -w %{http_code}删除接口的响应状态码是 204-w %{http_code}能看到返回码符合预期。到这里这个用户模块的 mock 服务已经可以交付给前端使用了。4.4 按模块拆分 Mock 文件前面我故意把所有接口写在一个 YAML 里是为了让你先看清整体结构。实际项目我不建议这么干。一个模块动辄几十个接口全写在一个文件里每次改配置都要在几百行里找不仅容易改错还会让 Git 冲突概率直线上升。更好的组织方式是这样mocks/ common.yaml user.yaml order.yaml payment.yaml启动时一次加载多个文件atest mock --port 8080 --file mocks/common.yaml --file mocks/user.yaml --file mocks/order.yaml公共配置放common.yaml比如统一的 CORS 头、健康检查接口、通用错误返回。业务模块各自管各自的文件谁负责哪个模块就改哪个文件。如果你用的 atest 版本支持加载目录那就更省事atest mock --port 8080 --file mocks/具体参数以atest mock --help输出为准。但这种“按目录组织配置”的思路在任何工具里都适用。5. 常见问题与排查技巧实录5.1 请求匹配不到一直返回 404这是 mock 服务最常遇到的问题。我的排查顺序是先看请求日志确认工具接收到的 method 和 path 长什么样。很多时候你以为前端请求的是/api/users实际可能带了一个末尾斜杠变成/api/users/导致匹配不上。解决办法很简单在配置里把路径变体都写上。比如- request: method: GET path: /api/users - request: method: GET path: /api/users/另一个隐蔽的原因是 query 参数类型问题。前面说过YAML 里把数字加引号转成字符串能规避不少类型不匹配的坑。如果还不行临时把 query 匹配条件删掉只匹配 method 和 path先确认基础路径能通再把参数一个个加回来。5.2 配置文件加载成功但规则不生效启动时 atest 没有任何报错curl 访问也通了但返回的不是你预期的那条数据而是默认响应。这种情况十有八九是规则顺序和精确度问题。mock 服务匹配规则一般有优先级最精确的规则会优先被选中。比如同时存在- request: method: GET path: /api/users/1 - request: method: GET path: /api/users/:id请求/api/users/1时应该命中带字面值1的规则而不是:id这个通配规则。如果你的 atest 版本没有内置这种优先级那就要手动把精确规则放在通配规则前面避免被“吞掉”。另外如果配置文件里有语法错误工具可能只是加载失败并不会影响已经启动的服务。这时候你需要重启服务并留意启动时有没有输出解析错误。我每次改完配置文件都会先跑一遍atest mock --file your.yaml --port 8080 --dry-run如果有 dry-run 或语法检查参数务必用一下省得反复重启浪费时间。5.3 前端跨域问题怎么处理前端项目通常跑在localhost:5173或localhost:3000mock 服务跑在localhost:8080跨域是必然的。解决方式有两种第一种是在 mock 配置里给每个响应加 CORS 头前面已经写过例子。第二种是让前端开发服务器做代理把/api前缀的请求转发到 mock 服务这样浏览器看到的是同源请求。我倾向于第二种方式因为这种方式更贴近生产环境部署。你在 vite 或 webpack 的 dev server 配置里加一个 proxy把/api代理到http://localhost:8080前端代码里仍然请求相对路径后续切换到真实后端时不需要改业务代码。5.4 端口占用导致启动失败启动命令执行后立刻报错提示端口被占用这是很常见的问题。macOS 和 Linux 用lsof查看lsof -i :8080Windows 用netstatnetstat -ano | findstr :8080查到占用进程之后要么干掉对应进程要么直接换一个端口启动 atestatest mock --port 18080 --file mock.yaml5.5 Mock 数据后续怎么复用很多项目把 mock 服务只当作联调工具后端接口就绪就扔了我觉得非常可惜。atest 的 mock 配置语言和测试用例语言语法相似这意味着你可以把 mock 文件里已经验证过的接口定义平滑改造成正式的 API 自动化测试用例。实际操作时我通常会在 mock 阶段就维护一份“接口契约”路径、方法、请求参数、响应结构都在 mock 文件里写清楚。后端接口完成后把 mock 文件里的response替换成预期的断言条件交给 atest 跑一遍就能复用大部分配置不需要从零开始写测试用例。最后说一点个人体会我在实际使用 atest v0.0.18 的 HTTP API Mock 功能时最大的感受是“简单到不太需要额外学习”。以前的 mock 方案要么依赖 Node 生态要么要写 Java 配置折腾一圈下来甚至比写真实接口还累。atest 的做法是把常用的接口模拟场景收敛成一份 YAML再用一条命令跑起来非常适合快速验证接口设计。如果你要开始在项目里用我的建议是从一个小模块试起先写两三个接口跑通 curl 验证再逐步扩展到全部接口。不要一开始就追求所有功能比如动态数据、复杂校验、优先级规则这些可以等用到的时候再看具体版本的文档。另外mock 配置一定要纳入版本管理和接口文档放在一起维护它本质上就是一份可执行的接口契约。等到后端接口真的写好了你回头看这些 mock 文件会发现它们带来的价值比“临时用一下”要多得多。