开发环境搭建

5 months ago
11db01e

开发环境搭建

本文档说明如何搭建 MLiev IAM 的本地开发环境。

环境准备

必需工具

  • Go 1.25+
  • Node.js 22+（前端开发时需要）
  • pnpm（前端包管理）
  • MySQL 8.0+ / PostgreSQL 13+ / SQLite 3
  • Redis 6.0+（可选，开发时可用内存缓存）

克隆项目

git clone <repository-url>
cd mliev-iam
go mod download

配置文件

cp config.yaml.example config.yaml

编辑 config.yaml，修改数据库和 Redis 连接信息。开发环境推荐使用 SQLite + 内存缓存：

server:
  mode: debug

database:
  driver: sqlite
  filepath: "./config/mliev_iam.db"

cache:
  driver: memory

启动开发模式

方式一：完整开发模式（推荐）

make dev

此命令会同时启动：

  • 前端 watch 模式（web-oidc, web-antd, web-install 热更新）
  • Go 后端（debug 模式）

方式二：仅后端

make dev-go
# 等效于：mode=debug go run .

方式三：直接运行

go run .

项目结构

mliev-iam/
├── app/                     # 应用核心代码
│   ├── controller/          # 控制器层 — 处理 HTTP 请求，解析参数
│   │   └── admin/           # 管理员专用控制器
│   ├── service/             # 服务层 — 业务逻辑
│   │   └── protocol/        # 协议处理器（OIDC/SAML/CAS）
│   ├── dao/                 # 数据访问层 — GORM 查询
│   ├── model/               # 数据模型 — GORM 模型定义
│   ├── dto/                 # 数据传输对象 — 请求/响应结构体
│   ├── middleware/          # 中间件 — 认证、权限、CORS
│   └── constants/           # 常量定义
├── cmd/                     # 程序入口和启动逻辑
├── config/                  # 配置管理
│   └── autoload/            # 自动加载的配置源
├── internal/                # 内部包
│   ├── interfaces/          # 接口定义（Assembly、Helper、Server）
│   ├── helper/              # Helper 单例（全局服务定位器）
│   └── pkg/                 # 基础设施包
├── admin-web/               # 前端项目（pnpm monorepo）
│   ├── apps/web-antd/       # 管理后台
│   ├── apps/web-oidc/       # OIDC 登录页
│   └── apps/web-install/    # 安装向导
├── static/                  # 前端构建产物（内嵌到二进制）
├── templates/               # HTML 模板文件
└── keys/                    # 密钥文件目录

开发约定

分层规范

  • Controller：负责参数解析、校验，调用 Service，返回响应。Handler 签名为 func(c *gin.Context, helper interfaces.HelperInterface)
  • Service：业务逻辑，通过 Helper 获取数据库、缓存等基础设施
  • DAO：数据库查询，使用 GORM 操作

路由注册

所有路由定义在 config/autoload/router.go，使用 deps.WrapHandler() 包装 handler 函数。

数据库操作

  • 所有模型使用 GORM 软删除（DeletedAt 字段）
  • 数据库迁移在启动时自动执行（GORM AutoMigrate）
  • 迁移模型列表定义在 config/autoload/migration.go

配置热重载

开发过程中修改 config.yaml 后，无需重启进程：

# 方式一：发送信号
kill -HUP $(pgrep mliev-iam)

# 方式二：调用 API
curl -X GET http://localhost:8080/api/system/reload

系统会重新执行 Assembly 流程，重载所有配置和服务。