AnCao/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。

项目概述

AnKao 是一个使用 Gin 框架构建的 Go Web 应用程序。该项目遵循整洁架构模式,具有清晰的关注点分离,并设计为支持数据库集成。

架构

请求流程

1. HTTP 请求到达运行在 8080 端口的 Gin 服务器
2. 请求通过 Gin 的默认中间件(Logger、Recovery)和自定义中间件
3. Gin 路由器匹配路由并将请求定向到相应的处理器
4. 处理器(位于 internal/handlers/)使用 *gin.Context 处理请求并返回 JSON 响应

中间件模式

Gin 中的中间件使用 gin.HandlerFunc 模式:

func MiddlewareName() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 预处理
        c.Next()
        // 后处理
    }
}

中间件在 main.go:15 中使用 r.Use() 注册。

模块结构

• main.go - 应用程序入口点,服务器配置和路由设置
• internal/handlers/ - HTTP 请求处理器,全部使用 *gin.Context 并返回 JSON 响应
• internal/middleware/ - Gin 中间件链(当前:自定义日志记录器)
• internal/models/ - 数据模型(目录已存在,准备用于数据库模型)
• pkg/config/ - 配置管理(目录已存在但尚未填充)

常用命令

开发

# 运行服务器
go run main.go

# 安装/更新依赖
go mod tidy

# 格式化代码
go fmt ./...

# 检查代码常见问题
go vet ./...

构建

# 构建二进制文件到 bin/server
go build -o bin/server.exe main.go

# 运行构建的二进制文件 (Windows)
.\bin\server.exe

# 运行构建的二进制文件 (Unix)
./bin/server

测试

# 运行所有测试
go test ./...

# 运行带覆盖率的测试
go test -cover ./...

# 运行特定包的测试
go test ./internal/handlers/

# 运行详细输出的测试
go test -v ./...

关键实现细节

• 框架: 使用 Gin v1.11.0
• 服务器端口: :8080 (在 main.go:22 中配置)
• 处理器签名: 所有处理器使用 func(c *gin.Context) 模式
• JSON 响应: 使用 c.JSON() 方法配合 gin.H{} 或结构体
• 导入路径: 使用模块名 ankao (在 go.mod 中定义)
• 路由注册: 路由在 main.go 中使用 r.GET()、r.POST() 等注册
• 中间件: 使用 r.Use() 全局应用或通过路由分组应用到特定路由

添加新功能

添加新处理器

1. 在 internal/handlers/ 中创建处理器函数,签名为 func(c *gin.Context)
2. 使用 c.JSON() 返回响应
3. 在 main.go 中注册路由(例如:r.GET("/path", handlers.YourHandler))

添加中间件

1. 在 internal/middleware/ 中创建返回 gin.HandlerFunc 的中间件
2. 使用 r.Use(middleware.YourMiddleware()) 全局应用或应用到路由组

数据库集成

项目已准备好进行数据库集成:

• 在 internal/models/ 中添加模型
• 考虑使用 GORM 或类似的 ORM
• 在 main.go 或单独的包中添加数据库初始化

前端开发规范

UI 组件使用原则

重要: 在开发前端页面时,必须优先使用 UI 框架的组件。

• 优先使用 antd-mobile 组件: 项目使用 antd-mobile 作为 UI 框架,开发时应优先查找并使用框架提供的组件
• 常用组件示例:
  • 表单输入: 使用 Input 组件,而非原生 <input>
  • 按钮: 使用 Button 组件,而非原生 <button>
  • 表单: 使用 Form 和 Form.Item 组件
  • 提示信息: 使用 Toast 组件,而非自定义提示框
  • 对话框: 使用 Dialog 组件
  • 列表: 使用 List 组件
• 仅在必要时自定义: 只有当 antd-mobile 没有提供对应组件时,才使用自定义组件
• 样式处理: 使用 CSS Modules (.module.less) 编写组件样式,避免全局样式污染

前端项目结构

• web/src/pages/ - 页面组件
• web/src/components/ - 可复用组件
• web/src/pages/*.module.less - 页面样式文件 (CSS Modules)