Logan.Li
286decf0b0
- 更新三种部署方式：embed 单容器、./aiops 根目录二进制 - 补充版本管理、release、lghost/aiops 镜像推送说明 - 修正过时的 docker 4 容器、backend/aiops、run.sh start 等描述 - 更新 project-structure、deployment、quick-start 等核心文档
199 lines
4.2 KiB
Markdown
199 lines
4.2 KiB
Markdown
# 开发规范
|
||
|
||
## 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`
|
||
|
||
### 统一响应格式
|
||
|
||
```go
|
||
// 成功响应
|
||
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 模板
|
||
|
||
```go
|
||
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：
|
||
|
||
```typescript
|
||
// 开发环境请求会被代理到 http://localhost:8080
|
||
fetch('/api/v1/servers')
|
||
```
|
||
|
||
## 测试
|
||
|
||
### 后端测试
|
||
|
||
```bash
|
||
cd backend
|
||
go test -v ./...
|
||
```
|
||
|
||
### 前端构建测试
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
npx tsc --noEmit # 类型检查（提交前零错误）
|
||
```
|
||
|
||
### 独立二进制构建
|
||
|
||
```bash
|
||
./run.sh build tag v1.5.0
|
||
./aiops version
|
||
```
|
||
|
||
## 日志
|
||
|
||
| 级别 | 使用场景 |
|
||
|------|---------|
|
||
| Info | 服务启动、正常操作 |
|
||
| Warn | 配置缺失、降级处理 |
|
||
| Error | 操作失败、异常 |
|
||
| Fatal | 启动失败、不可恢复 |
|
||
|
||
```go
|
||
log.Info("server started", zap.String("port", cfg.Port))
|
||
log.Error("database error", zap.Error(err))
|
||
```
|