# <<project_name_pascal>>

一个基于 **[Gin](https://gin-gonic.com/)** 框架的 Go Web 应用，由
[scaffold-gen](https://github.com/sunerpy/scaffold-gen) 生成。

---

## 必要说明 (What is this)

这是一个配置驱动的 Gin Web 项目：监听地址、端口写在 `configs/config.yaml`，
通过环境变量可覆盖任意配置项。业务代码按层分布在 `routers/`、`service/`、`model/` 目录下。

```
<<project_name_pascal>>/
├── config/                # 配置结构体
├── configs/               # ★ 配置文件写在这里（config.yaml）
├── core/                  # 核心应用代码
├── middleware/            # 自定义中间件
├── model/                 # 数据模型
├── routers/               # ★ API 路由
├── service/               # ★ 业务逻辑
├── util/                  # 工具函数
├── logs/                  # 运行时日志（自动创建）
└── main.go                # 应用入口
```

---

## 必要工具 (Requirements)

- **Go <<go_version>>+**（安装：https://go.dev/dl）
- **Docker**（可选，用于容器化部署）

---

## 使用方法 (Usage)

```bash
# 1. 整理依赖
go mod tidy

# 2. 启动服务
go run main.go

# 3. 验证接口
curl http://<<host>>:<<port>>/health
curl http://<<host>>:<<port>>/api/v1/ping
```

### 改监听地址 / 端口（Change host / port）

编辑 `configs/config.yaml`，**不要改代码**：

```yaml
server:
  host: "<<default_host>>"   # 改这里
  port: <<default_port>>     # 改这里
  mode: "debug"              # debug / release
```

也可通过环境变量覆盖：

```bash
SERVER_HOST=0.0.0.0 SERVER_PORT=9000 go run main.go
```

### Docker 部署

```bash
# Docker Compose（推荐）
docker-compose up -d

# 单独构建运行
docker build -t <<project_name_pascal>> .
docker run -p <<port>>:<<port>> <<project_name_pascal>>
```

---

## 开发流程 (Development)

### 新增路由

1. 在 `routers/` 注册新路由（或新建路由文件）。
2. 在 `service/` 实现对应业务逻辑。
3. 在 `model/` 定义数据模型（如需）。

### 新增配置项

1. 在 `config/config.go` 里扩展配置结构体。
2. 在 `configs/config.yaml` 里添加默认值。

### 常用命令

```bash
go test ./...   # 运行测试
go vet ./...    # 静态分析
gofmt -w .      # 格式化代码
```

---

## 推荐工具：CodeGraph (Recommended)

当项目变大、或你用 AI 编程助手时，推荐集成
**[codegraph-rust](https://github.com/sunerpy/codegraph-rust)** 作为代码分析工具：

- 基于 **tree-sitter + SQLite/FTS5** 的确定性代码知识图谱，**不含任何 AI/LLM**，输出字节级稳定。
- 提供符号 / 调用 / 依赖关系图，支持 **CLI 与 MCP server** 两种用法，可直接喂给 AI 编程 Agent。
- **单一二进制、易用、极高性能**：显著提升开发效率，同时大幅降低 token 消耗。

```bash
codegraph sync                 # 建立/更新索引
codegraph explore "your code"  # 探索符号与调用关系
```

---

## License

<<license>>
