Go / 系统课时
规划任务 API 的项目结构
规划任务 API 的项目结构
把任务 API 做成可发布程序时,最容易失控的是让 main 同时解析 HTTP、校验业务规则、访问存储。更稳妥的做法是先划清包边界:cmd 只负责组装与启动,HTTP 包只处理协议,业务包掌握 Task 与规则,存储实现通过接口接入。
学习目标
- 规划
cmd、internal与各业务包的职责边界。 - 让 HTTP、业务逻辑和存储依赖保持单向。
- 用一个最小可运行的
GET /tasks验证目录与依赖设计。
先确定依赖方向
这个示例使用 Go 1.22+,因为路由注册采用 ServeMux 的方法加路径模式 GET /tasks。编译期依赖保持为:入口包可以依赖各内部包,HTTP 适配层依赖业务包,存储实现也依赖业务包中的模型与接口;业务包本身不反向依赖 HTTP 或具体存储。

这里把 internal/task 作为核心包,因此 Store 接口由使用它的业务层定义。internal/store 只提供实现,main 决定注入哪一种实现。以后把内存存储换成 PostgreSQL 时,task.Service 不需要改成依赖数据库驱动。
把目录按职责切开
最小目录可以直接按下面四个位置创建,不必一开始就堆很多层级:
cmd/taskapi/main.go:读取配置、创建依赖、注册路由、启动进程。internal/task/model.go:定义Task、Store接口和Service。internal/httpapi/task_handler.go:把 HTTP 请求转换为业务调用,再把结果编码为 HTTP 响应。internal/store/memory.go:实现task.Store,以后可替换为 PostgreSQL、SQLite 等实现。
internal 适合放仅供当前项目使用的包,外部模块不能把这些包当公共库直接导入。此时没有对外复用需求,就不要为了“标准结构”额外创建空的 pkg、repository、usecase 等目录。
根目录放一个最小 go.mod:
module example.com/taskapi
go 1.22生效行为:模块内代码可以使用 example.com/taskapi/internal/... 作为导入路径,且下面的 ServeMux 路由模式在 Go 1.22 及更高版本可用。
用最小代码验证包边界
片段示例:下面四个文件属于同一个 example.com/taskapi 模块,必须按给出的路径一起保存后运行。
internal/task/model.go:
package task
import "context"
type Task struct {
ID int64 `json:"id"`
Title string `json:"title"`
Done bool `json:"done"`
}
// Store 由业务层定义,Service 因而不依赖具体数据库实现。
type Store interface {
List(context.Context) ([]Task, error)
}
// Service 是 HTTP 等入口调用的业务边界。
type Service struct {
store Store
}
func NewService(store Store) *Service {
return &Service{store: store}
}
func (s *Service) List(ctx context.Context) ([]Task, error) {
return s.store.List(ctx)
}internal/store/memory.go:
package store
import (
"context"
"example.com/taskapi/internal/task"
)
type Memory struct {
items []task.Task
}
func NewMemory() *Memory {
// 初始化为空切片,JSON 编码时得到 [] 而不是 null。
return &Memory{items: []task.Task{}}
}
func (m *Memory) List(context.Context) ([]task.Task, error) {
// 返回副本,避免调用方直接修改存储内部切片。
out := make([]task.Task, len(m.items))
copy(out, m.items)
return out, nil
}internal/httpapi/task_handler.go:
package httpapi
import (
"encoding/json"
"net/http"
"example.com/taskapi/internal/task"
)
func ListTasks(service *task.Service) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
// HTTP 层只把请求上下文传入业务层,不直接访问存储。
tasks, err := service.List(r.Context())
if err != nil {
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
// 业务对象只在边界处编码为 HTTP JSON 响应。
_ = json.NewEncoder(w).Encode(tasks)
}
}cmd/taskapi/main.go:
package main
import (
"fmt"
"log"
"net/http"
"example.com/taskapi/internal/httpapi"
"example.com/taskapi/internal/store"
"example.com/taskapi/internal/task"
)
func main() {
// main 只做依赖组装:具体存储 -> Service -> HTTP Handler。
memoryStore := store.NewMemory()
service := task.NewService(memoryStore)
mux := http.NewServeMux()
// Go 1.22+ 的 ServeMux 支持“方法 + 路径”模式。
mux.HandleFunc("GET /tasks", httpapi.ListTasks(service))
fmt.Println("task API listening on :8080")
if err := http.ListenAndServe(":8080", mux); err != nil {
log.Fatal(err)
}
}运行前先格式化并编译整个模块:
go fmt ./...
go build ./...预期结果:
<no output; exit status 0>然后启动程序:
go run ./cmd/taskapi预期输出:
task API listening on :8080另开一个终端验证路由:
curl -sS http://localhost:8080/tasks预期输出:
[]如果端口 8080 已被占用,把 main.go 中的监听地址改成未占用端口,并同步修改 curl 地址。
用路由职责反查包是否放对
规划后续接口时,可以先写职责表,再决定代码放在哪个包。这样能避免 handler 越写越厚。
| 路由 | HTTP 层负责 | task.Service 负责 |
Store 负责 |
|---|---|---|---|
GET /tasks |
读取请求上下文、设置 JSON 响应 | 获取任务列表 | 查询并返回任务 |
POST /tasks |
解码 title、映射状态码 |
去空白、拒绝空标题、创建任务 | 分配持久化 ID 并保存 |
PATCH /tasks/{id} |
解析路径 ID 与 JSON | 检查任务是否存在、应用状态变更 | 更新对应记录 |
一个直接的边界检查方法是搜索 cmd/taskapi/main.go:如果里面出现 json.NewDecoder、SQL、任务标题校验或任务状态判断,就说明业务或协议代码泄漏进了入口层。main 应只保留“创建什么、注入给谁、监听哪里”这类组装代码。
为后续存储替换留出接口
当前 Memory 只是开发期实现,但接口已经把替换点固定在 task.Store。以后新增 internal/store/postgres.go 时,让 Postgres 实现同一个 List(context.Context) ([]task.Task, error),再由 main 根据配置选择具体实现即可。
不要让 task.Service 导入 PostgreSQL 驱动,也不要让 httpapi 直接拿数据库连接。这样替换存储、给 Service 写假实现测试,或把 HTTP 换成其他入口时,核心业务包都不需要被迫跟着改。