服务端项目脚手架

后端脚手架存在形式

技术栈	工具 / 脚手架	特点
Go	go-zero、gin-scaffold、cobra CLI、buffalo	生成 API 层、Service 层、Repository 层，支持配置、数据库迁移、Dockerfile
Java	Spring Initializr、JHipster	Web 界面选择依赖、数据库、模块、生成完整项目骨架，支持 Maven / Gradle
Node.js	Nest CLI (nest new project)	自动生成模块、Controller、Service、DTO、测试模板
Python	Django startproject / FastAPI scaffold	自动生成项目结构、路由、配置、虚拟环境支持
Ruby	rails new project	完整 MVC 项目模板生成

✅ 特点：后端脚手架通常会带上：

• 基础目录结构（Controller / Service / Repository / Model / Middleware / Config / Test）
• 基础依赖（ORM、日志、配置、验证库）
• Dockerfile / docker-compose 模板
• CI/CD 配置模板（可选）
• 数据库迁移脚本模板（可选）
• API 文档生成集成（Swagger / OpenAPI）

1. 脚手架目标

• 统一项目结构
• 统一技术选型
• 统一编码规范
• 统一安全规范
• 统一部署规范
• 统一日志与监控

2. 技术栈约定（示例）

可替换为你自己的技术栈：

• 语言：Go / Java / Node.js
• 框架：Gin / Spring Boot / NestJS
• 数据库：MySQL / PostgreSQL
• 缓存：Redis
• 消息队列：Kafka / RabbitMQ
• API：RESTful
• 配置：YAML / ENV
• 文档：OpenAPI (Swagger)

3. 项目目录结构规范

3.1 标准目录结构

project-name/
├── cmd/                    # 启动入口
│   └── server/
│       └── main.go
├── config/                 # 配置文件
│   ├── config.yaml
│   └── config.prod.yaml
├── internal/               # 核心业务代码
│   ├── api/                # Controller 层
│   ├── service/            # 业务逻辑层
│   ├── repository/         # 数据访问层
│   ├── model/              # 数据模型
│   ├── middleware/         # 中间件
│   ├── router/             # 路由定义
│   ├── dto/                # 请求/响应结构体
│   └── constant/           # 常量定义
├── pkg/                    # 公共库
│   ├── logger/
│   ├── database/
│   ├── cache/
│   └── utils/
├── docs/                   # 文档
│   ├── api.md
│   └── db.md
├── scripts/                # 脚本
│   ├── migrate.sh
│   └── deploy.sh
├── test/                   # 测试
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── .env.example
├── README.md
└── go.mod / package.json / pom.xml

4. 分层架构规范

API(Controller)
   ↓
Service (业务逻辑)
   ↓
Repository (数据访问)
   ↓
Database

分层原则：

• Controller 不写业务逻辑
• Service 不写 SQL
• Repository 只负责数据访问
• Model 只表示数据结构

5. 统一返回结构

5.1 返回格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

5.2 错误返回

{
  "code": 10001,
  "message": "参数错误",
  "data": null
}

6. 配置管理规范

• 不同环境不同配置：

  • dev
  • test
  • prod

• 敏感信息不入仓库

• 使用 .env 或配置中心

db:
  host: localhost
  user: app
  password: ${DB_PASSWORD}

7. 日志规范

• 统一日志组件

• 日志级别：

  • DEBUG
  • INFO
  • WARN
  • ERROR

• 必须包含：

  • trace_id
  • user_id
  • 请求路径
  • 错误信息

8. 异常与错误码体系

• 使用统一错误码
• 不暴露堆栈
• 统一异常处理器（middleware）

10000 成功
20000 参数错误
30000 权限错误
40000 业务错误
50000 系统错误

9. 安全组件集成

脚手架必须内置：

• HTTPS
• JWT / Session
• 权限中间件
• 参数校验
• 防注入
• 限流中间件
• CORS 配置

10. API 文档

• 自动生成 Swagger / OpenAPI

• 接口必须有：

  • 参数说明
  • 示例
  • 错误码

11. 数据库迁移

• 必须支持版本化迁移

migrations/
├── 001_init.sql
├── 002_add_user.sql

12. 测试规范

• 单元测试
• 接口测试
• 覆盖率 > 60%

13. CI/CD 集成

推荐流程：

Git Commit
   ↓
CI Build
   ↓
Test
   ↓
Docker Build
   ↓
Deploy

14. Docker 化

Dockerfile 示例：

FROM golang:1.22
WORKDIR /app
COPY . .
RUN go build -o app
CMD ["./app"]

15. README 标准模板

README 必须包含：

• 项目简介
• 技术栈
• 目录结构
• 启动方式
• 接口文档地址
• 部署方式

16. 脚手架初始化命令（建议）

例如：

create-backend-app my-project

自动生成：

• 项目结构
• 基础代码
• 配置文件
• Dockerfile
• CI 配置

17. 脚手架核心清单（Checklist）

• [x] 目录结构
• [x] 日志
• [x] 错误码
• [x] 鉴权
• [x] 配置管理
• [x] API 文档
• [x] 数据库迁移
• [x] Docker
• [x] 测试模板
• [x] CI/CD

18. 核心价值总结

脚手架 = 规范 + 工具 + 最佳实践的固化

带来的好处：

• 新项目 5 分钟启动
• 新人 1 天上手
• Bug 减少
• 安全提升
• 可维护性大幅提高

19. 推荐增强模块（可选）

• 任务调度（cron）
• 消息队列模块
• 文件服务模块
• 搜索模块
• 多租户模块
• 插件化架构

20. 示例

以 Go 框架 gin 为例，推荐脚手架：go-gin-example， 或者 go install github.com/go-nunu/nunu@latest。

2.1 克隆仓库

git clone https://github.com/EDDYCJY/go-gin-example.git my-gin-project
cd my-gin-project

2.2 安装依赖

go mod tidy

Windows 下无需交互认证，完全开箱可用

2.3 启动项目

go run main.go

默认端口：http://localhost:8080

2.4 核心目录结构

my-gin-project/
├── cmd/            # 启动入口
├── config/         # 配置文件
├── model/          # 数据模型
├── routers/        # 路由
├── service/        # 业务逻辑
├── middleware/     # 中间件
├── docs/           # Swagger 文档
├── scripts/        # 启动/迁移脚本
├── pkg/            # 公共库
├── main.go
└── go.mod

2.5 特性

• JWT 验证
• RBAC 权限
• 日志中间件
• 参数校验
• Swagger 自动生成
• MySQL + Redis 支持
• RESTful API 示例