mengstack-website/guide/project-structure.md

title
项目结构说明 | MengStack目录规范详解 - MengStack官方文档

项目结构

mengstack/
├── cmd/
│   └── server/
│       └── main.go              # 应用入口，Swagger 注解
├── configs/
│   └── config.yaml              # 默认配置文件
├── docs/                        # Swagger 自动生成文档
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── internal/
│   ├── kernel/                  # 第一层：零业务语义基础组件
│   │   └── response/            # 统一响应格式
│   ├── app/                     # 第二层：应用基础设施
│   │   ├── cache/               # Redis 缓存模块
│   │   ├── database/            # PostgreSQL 数据库模块
│   │   ├── health/              # 健康检查
│   │   ├── middleware/          # 全局中间件（CORS、请求ID、日志）
│   │   └── app.go               # fx 容器组装
│   ├── config/                  # 配置加载（Viper）
│   ├── logger/                  # 日志初始化（Zap）
│   └── modules/                 # 第三层：业务模块
│       └── auth/                # 认证模块
│           ├── domain/          # 领域层：实体、值对象、接口定义
│           ├── application/     # 应用层：业务逻辑编排
│           ├── infrastructure/  # 基础设施层：GORM/Redis 实现
│           └── interfaces/      # 接口层：HTTP Handler + 路由
├── migrations/                  # 数据库迁移文件
├── test/                        # 集成测试
├── docker-compose.yml           # Docker 编排
├── Makefile                     # 构建命令
├── AGENTS.md                    # AI 辅助开发指南
└── go.mod                       # Go 模块定义

目录职责

cmd/server/

应用入口，仅负责组装和启动。包含 Swagger 全局注解。

internal/kernel/

零业务语义的基础组件。不包含任何业务概念，只提供通用工具：

• response/ — 统一响应格式 {code, message, data, trace_id}
• 后续可扩展：paginator/、errors/ 等

internal/app/

应用基础设施，连接 kernel 和外部世界：

• database/ — GORM + PostgreSQL 初始化和生命周期
• cache/ — Redis 客户端初始化和生命周期
• middleware/ — 请求 ID、请求日志、CORS
• health/ — 健康检查端点

internal/modules/

业务模块目录，每个模块独立自包含，遵循四层模式。

configs/

默认配置文件，运行时可通过环境变量覆盖。

migrations/

数据库迁移文件，使用 golang-migrate 管理。