构建一个订单服务

我们会做出什么

一家小店需要记录订单。提交商品编号和数量后，服务生成订单号；店员可以查回订单，也可以取消。下面就是创建一笔订单时，客户端和服务之间发生的事情。

订单服务 · 接口示例127.0.0.1:8080

客户端提交

POST /orders

{
  "sku": "coffee",
  "quantity": 2
}

服务端返回

201 Created

{
  "id": "a17c…8e42",
  "sku": "coffee",
  "quantity": 2,
  "status": "pending",
  "created_at": "2026-10-21T08:00:00Z"
}

展示的是接口内容，不是在线运行的服务。ID 已缩写，实际 ID 和时间由每次请求生成。

创建、查询与取消用真实请求理解路由、参数校验和业务规则。
重启后仍能查到将内存存储换成 SQLite，验证订单确实保存。
两个入口，同一笔订单让 HTTP 和 TCP 调用同一个业务服务。

先在本机运行成品

需要会基本 Go 语法、能在终端执行命令。Go 版本至少为 1.26.9，这是本例固定依赖的 KPro v0.2.1 的要求。第一次下载依赖需要网络；之后不需要安装数据库服务器，SQLite 数据库就是一个本地文件。

下载完整 orders 工程 ZIP ↓ 在网页中阅读全部源码 →

解压后进入包含 go.mod 的 orders 目录。以下命令都在这个目录执行。如果你拿的是官网源码，位置是 examples/orders。

终端 1 · 启动服务

go version
go mod download
go run ./cmd/orders

看到 listeners ready 后保持这个终端运行。当前目录会出现 orders.db，它存放稍后创建的订单。另开一个终端，进入同一目录：

终端 2 · 实际操作一笔订单

go run ./cmd/check

检查工具向你的服务发送真实 HTTP 请求，会打印每次响应的完整 JSON。按顺序应当得到下面这些状态码：

预期结果 · id 和时间由本次运行生成

GET /readyz                         → 200
POST /orders                        → 201
GET /orders/本次生成的ID              → 200
POST /orders（quantity 为 0）         → 422
POST /orders/本次生成的ID/cancel       → 200
POST /orders/本次生成的ID/cancel       → 200

工具最后打印订单 ID，请记下来。此时订单的状态已经是 cancelled。停止终端 1，再执行相同启动命令，用这个 ID 查询，仍应该得到同一笔订单。不要换一个工作目录，否则默认数据库路径也会改变。

手动查询 · 把 ORDER_ID 替换成刚才的 ID

curl -i http://127.0.0.1:8080/orders/ORDER_ID

Windows PowerShell 中请用 curl.exe 代替 curl，避免某些版本把它当作 PowerShell 命令别名。更复杂的 JSON 请求都使用工程内的文件，避免命令行引号差异。

一笔订单会经过哪里

HTTP 客户端POST /orders

→

httpapi读 JSON，写响应

→

order.Service校验，执行业务规则

→

Storememory 或 sqlite

main 先选择存储，app.New 再把图里的对象连起来。请求到来时，main 不会重新执行；已经注册的 HTTP handler 调用已经创建的 Service，Service 再调用那个存储对象。

你在工程中寻找的东西	实际文件	它不负责什么
程序入口、参数、退出信号	cmd/orders/main.go	不解析每个订单请求
把组件接在一起	internal/app/app.go	不判断订单是否合法
HTTP 路由与 JSON	internal/httpapi/api.go	不写 SQL
订单、校验、取消规则	internal/order/service.go	不知道请求来自 HTTP 还是 TCP
临时存储 / 持久化	internal/memory/store.go internal/sqlite/store.go	不决定 HTTP 状态码
TCP 消息入口	internal/messageapi/api.go	不创建第二套订单业务
可运行的客户端	cmd/check/main.go internal/tcpclient/client.go	不代替服务端校验

怎样使用这份教程

我们采用先使用成品，再逐段读懂并修改它的方式。下载包一开始就包含完整工程；正文会标出正在阅读的文件和函数。第 1 章另有一个独立的单文件起点，后面再逐步看完整服务。

先完成第 1–4 章，你应该能追踪一次创建请求；第 5–7 章解释存储、第二种协议和并发状态变化；第 8–9 章练习运行维护与需求修改。源码可以直接在本站阅读，核心逻辑都在正文讲解，不需要先把框架仓库翻一遍。