Become a sponsor
4.6 目录结构设计
概述
目录即架构：internal 对外不可见、utility 无业务语义、一模块四文件同名成套。本页解释"为什么这样分"，目录树本身见 1.3 项目目录结构。
顶层划分的逻辑
| 目录 | 定位 | 判定标准 |
|---|---|---|
| internal/ | 业务代码 | 含业务语义，Go 编译器层面禁止外部引用 |
| utility/ | 基础设施 | 无业务语义，任何项目可复用 |
| cmd/ | 可执行入口 | package main，只做装配不做逻辑 |
| templates/ | 生成器模板 | 渲染产物是代码，非运行时依赖 |
| config/ resource/ | 运行期数据 | 配置与静态资源 |
| deploy/ | 交付物料 | Docker/Nginx，不参与编译 |
| document/ | 项目文档 | 规约与 SQL 脚本 |
| ui/ | 前端 | 独立工具链，独立生命周期 |
internal 内部的分层逻辑
text
model/ 数据形态的定义（dto 契约、db 连接、hooks 红线）
router/ HTTP 装配（注册引擎 + 元数据）
middleware/ 横切（每个文件一个关注点）
handler/ 入口（最薄）
service/ 业务（最厚）
repository/ 数据访问（唯一 SQL 触点）
task/ 后台（与请求链无关的定时逻辑）
server/ 生命周期（启动与关闭）
consts/ 跨层共享的常量
migrate/ 独立工具引擎（跨库迁移）依赖只能向下：repository 不 import service，service 不 import handler。
一模块四文件的价值
同名的 internal/{model/dto,repository,service,handler}/{module}.go：
- 可检索：
example一个关键词命中全链路 - 可生成：生成器按同名规则产出与覆盖
- 可审查：PR 按模块聚合，四文件即一个完整变更单元
- 规约自明：新模块不问即知放哪里
utility 的边界
utility 包禁止 import internal（基础设施不依赖业务）。内部互相引用仅限极底层（如 logger 被各包使用）。每个包一个关注点，13 个包与 config.yaml 配置节大体一一对应。
运行期目录
| 目录 | 内容 | 处置 |
|---|---|---|
| log/ | zap 文件日志 | LogClean 任务按保留期清理 |
| upload/ | 上传文件（temp + 正式子目录） | temp 按天清理；生产由 nginx 直供 |
两者都在 .gitignore，不进版本库。
前后端的对称性
text
后端 RouteSpec Path: /api/example/page
前端 api 模块: ui/src/api/tool/example.ts → url: '/example/page'
后端菜单 component: tool/example/index
前端页面: ui/src/views/tool/example/index.vue五处路径同构——这是生成器能一键打通前后端的原因。