一个基于 Go 语言的现代化 Web 应用程序示例，采用清洁架构设计，集成了 Gin、GORM、Zap 等主流框架。

• 现代化架构: 采用分层架构设计，代码结构清晰
• 高性能: 基于 Gin 框架，提供高性能的 HTTP 服务
• 数据库支持: 集成 GORM v2，支持 PostgreSQL 和 MySQL
• 代码生成: 使用 GORM Gen 自动生成数据访问层代码
• 结构化日志: 集成 Zap 日志库，支持结构化日志输出
• 配置管理: 基于 Viper 的灵活配置管理，支持环境变量覆盖
• 优雅关闭: 支持服务器优雅关闭
• 中间件: 内置请求日志、错误处理、恢复、请求ID等中间件
• 依赖注入: 使用 Google Wire 自动注入，模块解耦、可测试性更佳
• 缓存/Redis: 集成 go-redis v9，支持主从（读写分离）与统一缓存封装
• 鉴权: 基于 JWT 的登录、刷新与路由保护

go-web-demo/
├── cmd/                          # 应用程序入口
│   ├── gen/                      # GORM Gen 代码生成器
│   │   └── main.go
│   └── server/                   # HTTP 服务（Wire 注入入口）
│       ├── main.go
│       ├── wire.go               # Wire provider（需 wire 生成）
│       └── wire_gen.go           # 由 wire 生成
├── configs/
│   └── config.example.yaml       # 配置示例（生产请使用环境变量/挂载配置）
├── docs/                         # 设计与使用文档
│   ├── wire-dependency-injection.md
│   ├── redis-integration.md
│   ├── api-response-structure.md
│   └── adding-new-modules-with-wire.md
├── internal/
│   ├── app/
│   │   ├── auth/                 # JWT 管理（签发、校验等）
│   │   ├── controller/           # 控制器（Example/User/Auth）
│   │   ├── router/               # 路由装配
│   │   │   ├── middleware/       # 中间件（Auth/Log/Recovery/RequestID/ErrorHandler）
│   │   │   └── engine_alias.go
│   │   ├── service/              # 业务服务层
│   │   └── server.go             # HTTP Server 封装
│   ├── cache/                    # Redis 客户端与缓存封装
│   │   ├── redis.go              # Master/Slave 客户端管理
│   │   └── redis_cache.go        # 统一缓存接口实现
│   ├── config/                   # 配置加载（Viper）与默认值
│   ├── db/
│   │   ├── auto_migrate.go
│   │   ├── database.go
│   │   ├── dao/                  # 数据访问对象
│   │   ├── model/                # 数据模型（生成）
│   │   ├── query/                # 查询代码（生成）
│   │   └── repository/           # 仓储封装
│   ├── die/                      # 统一错误码与业务错误
│   └── logger/                   # 日志（Zap）
├── go.mod
├── go.sum
├── Makefile
└── tools.go

• Web 框架: Gin
• ORM/生成: GORM, GORM Gen
• 依赖注入: Google Wire
• 缓存/Redis: go-redis v9
• 日志: Zap
• 配置: Viper
• 鉴权: JWT（自实现 Manager + 中间件）
• 数据库: PostgreSQL / MySQL
• Go 版本: 1.24.6

• Go 1.24.6 或更高版本
• PostgreSQL 或 MySQL
• Redis（可将 master/slave 指向同一实例用于本地开发）

1. 克隆项目

   git clone https://github.com/hakurei/go-web-demo.git
   cd go-web-demo
   

2. 安装依赖

   make tidy
   

3. 配置应用

   复制示例配置（或直接使用环境变量覆盖）：

   cp configs/config.example.yaml configs/config.yaml
   

   关键配置项（节选，更多见 internal/config/config.go 默认值与示例文件）：

   db:
     host: 127.0.0.1
     port: 5432
     user: postgres
     password: "your_password"
     name: your_database
     sslmode: disable
   
   redis:
     master:
       addr: localhost:6379
       password: ""
       db: 0
     slave:
       # 本地可与 master 指向同一实例
       addr: localhost:6379
       password: ""
       db: 0
     cache:
       keyPrefix: "go_web_demo:"
       defaultExpiration: 3600s
       cleanupInterval: 600s
   
   jwt:
     secret: "change-me"
     issuer: "go-web-demo"
     accessTokenTTL: 15m
     refreshTokenTTL: 168h
     header: "Authorization"
     tokenPrefix: "Bearer"
   

4. 生成数据访问层代码

   make gen
   

5. 运行应用

   make run
   

   服务器将在 http://localhost:8080 启动

可通过 APP_ 前缀覆盖任意配置，例如：

# App
export APP_APP_ENV=dev
export APP_APP_MODE=debug
export APP_APP_HTTP_HOST=0.0.0.0
export APP_APP_HTTP_PORT=8080

# DB
export APP_DB_HOST=localhost
export APP_DB_PORT=5432
export APP_DB_USER=postgres
export APP_DB_PASSWORD=password
export APP_DB_NAME=mydb

# Redis
export APP_REDIS_MASTER_ADDR=localhost:6379
export APP_REDIS_SLAVE_ADDR=localhost:6379

# JWT
export APP_JWT_SECRET=change-me
export APP_JWT_ISSUER=go-web-demo
export APP_JWT_HEADER=Authorization
export APP_JWT_TOKENPREFIX=Bearer

make run

• POST /api/auth/login - 登录，返回 access/refresh token
• POST /api/auth/refresh - 刷新 access token

• GET /api/examples?limit=10 - 获取示例列表（白名单，无需鉴权）

• POST /api/users - 创建用户
• GET /api/users/:id - 获取用户
• PUT /api/users/:id - 更新用户
• DELETE /api/users/:id - 删除用户
• GET /api/users - 分页查询用户

所有 API 响应都遵循统一的格式：

{
  "code": 0,
  "message": "ok",
  "data": {},
  "trace_id": "request-id-here"
}

1. 定义数据模型

   在数据库中创建表，然后运行代码生成：

   make gen
   

2. 创建 DAO 层

   在 internal/db/dao/ 目录下创建数据访问对象

3. 创建 Service 层

   在 internal/app/service/ 目录下创建业务逻辑

4. 创建 Controller 层

   在 internal/app/controller/ 目录下创建控制器

5. 注册路由

   在 cmd/server/main.go 中注册新的控制器

项目使用 GORM Gen 进行代码生成，配置文件位于 cmd/gen/main.go。

运行代码生成：

make gen

项目内置中间件：

• RequestID: 请求 ID 生成与透传
• Recovery: 异常恢复（统一 500 JSON）
• ErrorHandler: 统一错误处理与业务错误码映射
• Logging: 结构化访问日志（响应时长、状态码、trace_id）
• Auth (JWT): 基于配置自动挂载全局鉴权，中间件在 Router 统一装配；白名单已放行 /healthz, /api/auth/login, /api/auth/refresh, /api/examples

可在 internal/app/router/middleware/ 中扩展自定义中间件。

运行测试：

make test

app:
  name: go-web-demo      # 应用名称
  env: dev               # 环境：dev/prod
  mode: debug            # Gin 模式：debug/release
  http:
    host: 0.0.0.0        # 监听地址
    port: 8080           # 监听端口

log:
  level: info                    # 日志级别
  format: json                   # 日志格式：json/console
  outputPaths: ["stdout"]        # 输出路径
  errorOutputPaths: ["stderr"]   # 错误输出路径
  enableStacktrace: false        # 是否启用堆栈跟踪

db:
  # 或使用 dsn 直接提供连接串（优先生效）
  # dsn: "postgres://user:pass@host:5432/dbname?sslmode=disable"
  host: 127.0.0.1
  port: 5432
  user: postgres
  password: "password"
  name: postgres
  sslmode: disable
  maxOpenConns: 20
  maxIdleConns: 10
  connMaxLifetime: 1h

redis:
  master:
    addr: localhost:6379
    password: ""
    db: 0
  slave:
    # 本地可与 master 相同
    addr: localhost:6379
    password: ""
    db: 0
  cache:
    keyPrefix: "go_web_demo:"
    defaultExpiration: 3600s
    cleanupInterval: 600s

jwt:
  secret: "change-me"
  issuer: "go-web-demo"
  accessTokenTTL: 15m
  refreshTokenTTL: 168h
  header: "Authorization"
  tokenPrefix: "Bearer"

创建 Dockerfile：

FROM golang:1.24.6-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
# 生成 wire 代码（若 wire_gen.go 未提交或需更新）
RUN cd cmd/server && go install github.com/google/wire/cmd/wire@latest && wire
RUN CGO_ENABLED=0 GOOS=linux go build -o main ./cmd/server

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/

COPY --from=builder /app/main .
COPY --from=builder /app/configs ./configs

ENV APP_APP_MODE=release
CMD ["./main"]

在生产环境中，建议使用环境变量来配置应用：

export APP_APP_ENV=prod
export APP_APP_MODE=release
export APP_DB_HOST=your-db-host
export APP_DB_PASSWORD=your-db-password
# ... 其他配置

欢迎提交 Issue 和 Pull Request！

本项目采用 MIT 许可证。

如有问题，请提交 Issue 或联系项目维护者。