attacker
97c4207ff8
- 目录重构: app/ -> frontend/，与 backend/ 并列 - 数据库: 默认 SQLite（零配置），修复 DSN() bug - run.sh: 一键启动前后端，支持 start/stop/restart/status - Makefile: install/dev/build/lint/clean 快捷命令 - vite.config.ts: 配置 dev server 端口 5173 + API 代理到 8080 - config.yaml: SQLite 默认配置，开箱即用 - docs/: 完整开发文档（项目结构/API/数据库/规范/部署） - 修复: GORM foreign key 关联声明 - 修复: go get gorm.io/driver/sqlite 依赖
189 lines
3.9 KiB
Markdown
189 lines
3.9 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）
|
||
|
||
### 目录职责
|
||
|
||
| 目录 | 职责 |
|
||
|------|------|
|
||
| `cmd/` | 应用入口 |
|
||
| `internal/handlers/` | HTTP 请求处理（参数校验、响应） |
|
||
| `internal/models/` | 数据模型定义 |
|
||
| `internal/config/` | 配置管理 |
|
||
| `internal/middleware/` | 中间件 |
|
||
| `internal/routes/` | 路由注册 |
|
||
| `pkg/database/` | 数据库连接 |
|
||
| `pkg/logger/` | 日志工具 |
|
||
|
||
### 命名规范
|
||
|
||
- 文件名：`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 app
|
||
npm run build # TypeScript 编译 + Vite 构建
|
||
```
|
||
|
||
## 日志
|
||
|
||
| 级别 | 使用场景 |
|
||
|------|---------|
|
||
| Info | 服务启动、正常操作 |
|
||
| Warn | 配置缺失、降级处理 |
|
||
| Error | 操作失败、异常 |
|
||
| Fatal | 启动失败、不可恢复 |
|
||
|
||
```go
|
||
log.Info("server started", zap.String("port", cfg.Port))
|
||
log.Error("database error", zap.Error(err))
|
||
```
|