aiops/docs/development-guide.md

开发规范

Git 工作流

分支策略

分支	说明
main / master	生产分支，保护分支
dev	开发集成分支
feature/*	功能分支
fix/*	修复分支
hotfix/*	紧急修复

提交规范

<type>: <description>

- 变更点 1
- 变更点 2

Type 列表：

• feat: 新功能
• fix: Bug 修复
• refactor: 重构
• docs: 文档
• style: 样式
• test: 测试
• chore: 构建/工具

示例：

feat: 添加服务器批量导入功能

- 支持 Excel 导入
- 支持云平台同步

后端规范（Go）

目录职责

目录	职责
main.go / embed.go	应用入口 + 前端嵌入
controller/	HTTP 请求处理（参数校验、响应）
model/	数据模型定义
config/	配置管理 (Viper)
middleware/	JWT / 日志 / CORS 中间件
router/	路由注册
service/ / repository/	业务逻辑 / 数据访问
pkg/database/	数据库连接 + AutoMigrate
pkg/logger/	日志工具
static/	前端 embed 静态资源

命名规范

• 文件名：snake_case.go
• 类型/方法：PascalCase
• 变量：camelCase
• 常量：PascalCase 或 ALL_CAPS

统一响应格式

// 成功响应
c.JSON(http.StatusOK, models.Response{
    Code:    200,
    Message: "success",
    Data:    result,
})

// 分页响应
c.JSON(http.StatusOK, models.Response{
    Code:    200,
    Message: "success",
    Data: models.ListResponse{
        List:  items,
        Total: total,
    },
})

// 错误响应
c.JSON(http.StatusBadRequest, models.Response{
    Code:    400,
    Message: "参数错误: " + err.Error(),
})

Handler 模板

func (h *ServerHandler) CreateServer(c *gin.Context) {
    // 1. 参数绑定
    var req models.ServerRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, models.Response{Code: 400, Message: err.Error()})
        return
    }

    // 2. 业务逻辑
    server := models.Server{
        Name: req.Name,
        IP:   req.IP,
    }
    if err := h.db.Create(&server).Error; err != nil {
        c.JSON(http.StatusInternalServerError, models.Response{Code: 500, Message: "创建失败"})
        return
    }

    // 3. 返回结果
    c.JSON(http.StatusOK, models.Response{Code: 200, Message: "创建成功", Data: server})
}

注意事项

• GORM First() 连续查询会带上次 ID，用 Take() 代替
• Go 编译前设置 GOPROXY=https://goproxy.cn,direct
• SQLite 需要 CGO_ENABLED=1
• JWT 使用 golang-jwt/jwt/v5，jwt.TimeFunc() 已移除，用 time.Now()

前端规范（React + TypeScript）

目录职责

目录	职责
src/components/*/	业务组件
src/components/ui/	shadcn/ui 基础组件
src/hooks/	自定义 Hooks
src/lib/	工具函数
src/services/	API 封装
src/store/	Zustand 状态管理
src/types/	TypeScript 类型
src/mocks/	Mock 数据

命名规范

• 组件文件：PascalCase.tsx（如 ServerManager.tsx）
• 工具文件：camelCase.ts（如 formatDate.ts）
• 组件名：PascalCase

UI 设计原则

• 能去掉的装饰都去掉（无边框、无多余分隔线）
• 选中态用 bg-surface-active，不用彩色高亮
• 页面打开即用，不需要额外的"新建"按钮跳转
• 操作成功不弹 toast，仅在失败时提示

API 调用

前端通过 Vite 代理访问后端 API：

// 开发环境请求会被代理到 http://localhost:8080
fetch('/api/v1/servers')

测试

后端测试

cd backend
go test -v ./...

前端构建测试

cd frontend
npm run build
npx tsc --noEmit   # 类型检查（提交前零错误）

独立二进制构建

./run.sh build tag v1.5.0
./aiops version

日志

级别	使用场景
Info	服务启动、正常操作
Warn	配置缺失、降级处理
Error	操作失败、异常
Fatal	启动失败、不可恢复

log.Info("server started", zap.String("port", cfg.Port))
log.Error("database error", zap.Error(err))