Go / 系统课时

规划任务 API 的项目结构

规划任务 API 的项目结构

把任务 API 做成可发布程序时,最容易失控的是让 main 同时解析 HTTP、校验业务规则、访问存储。更稳妥的做法是先划清包边界:cmd 只负责组装与启动,HTTP 包只处理协议,业务包掌握 Task 与规则,存储实现通过接口接入。

学习目标

  • 规划 cmd、internal 与各业务包的职责边界。
  • 让 HTTP、业务逻辑和存储依赖保持单向。
  • 用一个最小可运行的 GET /tasks 验证目录与依赖设计。

先确定依赖方向

这个示例使用 Go 1.22+,因为路由注册采用 ServeMux 的方法加路径模式 GET /tasks。编译期依赖保持为:入口包可以依赖各内部包,HTTP 适配层依赖业务包,存储实现也依赖业务包中的模型与接口;业务包本身不反向依赖 HTTP 或具体存储。

任务 API 的包边界与依赖方向

这里把 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:

text
module example.com/taskapi

go 1.22

生效行为:模块内代码可以使用 example.com/taskapi/internal/... 作为导入路径,且下面的 ServeMux 路由模式在 Go 1.22 及更高版本可用。

用最小代码验证包边界

片段示例:下面四个文件属于同一个 example.com/taskapi 模块,必须按给出的路径一起保存后运行。

internal/task/model.go:

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:

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:

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:

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)
	}
}

运行前先格式化并编译整个模块:

bash
go fmt ./...
go build ./...

预期结果:

text
<no output; exit status 0>

然后启动程序:

bash
go run ./cmd/taskapi

预期输出:

text
task API listening on :8080

另开一个终端验证路由:

bash
curl -sS http://localhost:8080/tasks

预期输出:

json
[]

如果端口 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 换成其他入口时,核心业务包都不需要被迫跟着改。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

规划任务 API 的项目结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通