# <<ProjectName>>

一个基于 **[go-zero](https://go-zero.dev/)** 的微服务项目，由
[scaffold-gen](https://github.com/sunerpy/scaffold-gen) 生成。

> ⚠️ **注意**：go-zero 脚手架生成目前尚未实现（`GenKind::Unimplemented`）。
> 本 README 为未来实现准备，模板内容仅供参考。

---

## 必要说明 (What is this)

这是一个 go-zero 微服务项目，包含 HTTP API 服务和 gRPC RPC 服务：

- **配置和代码分离**：地址、端口写在 `etc/` 目录下的 YAML 文件里，**不用碰代码**。
- **双服务**：`api/`（HTTP）和 `rpc/`（gRPC），可独立启动。
- **业务代码集中**：新增逻辑写在 `api/internal/logic/` 或 `rpc/internal/logic/`。

```
<<ProjectName>>/
├── api/                        # HTTP API 服务
│   ├── internal/
│   │   ├── handler/            # HTTP handlers
│   │   ├── logic/              # ★★★ 业务逻辑写在这里 ★★★
│   │   ├── svc/                # 服务上下文
│   │   ├── types/              # 请求/响应类型
│   │   └── config/             # 配置结构体
│   ├── api.api                 # ★ API 定义文件（goctl 驱动）
│   └── main.go
├── rpc/                        # gRPC 服务
│   └── <<ProjectName>>.proto   # ★ Proto 定义文件
├── model/                      # 数据模型
├── common/                     # 公共工具
│   ├── errorx/                 # 错误处理
│   ├── response/               # 响应工具
│   └── middleware/             # 中间件
├── etc/                        # ★ 配置文件写在这里
└── deploy/                     # 部署文件（Docker / k8s）
```

---

## 必要工具 (Requirements)

- **Go 1.21+**（安装：https://go.dev/dl）
- **goctl** —— go-zero 代码生成工具：

  ```bash
  go install github.com/zeromicro/go-zero/tools/goctl@latest
  ```

- **Docker**（可选，用于容器化部署）

---

## 使用方法 (Usage)

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

# 2. 启动 API 服务
cd api && go run main.go -f etc/api.yaml

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

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

编辑 `etc/api.yaml`，**不要改代码**：

```yaml
Name: api
Host: <<Host>>
Port: <<Port>>
```

### 启动 RPC 服务

```bash
cd rpc && go run main.go -f etc/rpc.yaml
```

---

## 开发流程 (Development)

### 新增 API 端点

1. 在 `api/api.api` 里定义新端点。
2. 运行 `./generate-api.sh`（goctl 生成代码）。
3. 在生成的 `logic/` 文件里实现业务逻辑。

### 新增 RPC 服务

1. 在 `rpc/<<ProjectName>>.proto` 里添加服务定义。
2. 运行 `./generate-rpc.sh`（goctl 生成代码）。
3. 在生成的文件里实现服务逻辑。

### 数据库集成（Database integration）

用 goctl 生成 Model 代码：

```bash
goctl model mysql datasource \
  -url="user:password@tcp(127.0.0.1:3306)/database" \
  -table="table_name" \
  -dir="./model"
```

### Docker 部署

```bash
cd deploy/docker && docker-compose up -d
```

---

## 推荐工具：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

This project is licensed under the MIT License.
