# 快速入门

<cite>
**本文档中引用的文件**  
- [Makefile](file://Makefile)
- [hack/hack.mk](file://hack/hack.mk)
- [main.go](file://main.go)
- [manifest/docker/docker-compose.yml](file://manifest/docker/docker-compose.yml)
- [utility/config/database.go](file://utility/config/database.go)
- [internal/dao/internal/v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [internal/dao/internal/v_1_sys_config_dict.go](file://internal/dao/internal/v_1_sys_config_dict.go)
</cite>

## 目录
1. [简介](#简介)
2. [开发环境配置](#开发环境配置)
3. [依赖安装与构建](#依赖安装与构建)
4. [数据库初始化](#数据库初始化)
5. [项目启动](#项目启动)
6. [Hello World 示例：调用基础 API](#hello-world-示例调用基础-api)
7. [常见问题排查指南](#常见问题排查指南)
8. [总结](#总结)

## 简介

本指南旨在为新开发者提供 `kami_backend` 项目的快速入门说明。通过本指南，您将在 15 分钟内完成开发环境的搭建、依赖安装、数据库初始化、服务启动，并成功调用一个基础 API 端点。本项目使用 GoFrame 框架构建，通过 `Makefile` 提供标准化操作命令，简化开发流程。

**Section sources**
- [main.go](file://main.go#L1-L50)
- [Makefile](file://Makefile#L1-L6)

## 开发环境配置

在开始之前，请确保您的开发环境已安装以下工具：

- **Go 1.20+**：本项目基于 Go 语言开发，建议使用 1.20 或更高版本。
- **GF CLI 工具**：GoFrame 官方命令行工具，用于代码生成和项目管理。
- **Docker 和 Docker Compose**：用于容器化部署和依赖服务管理。
- **Git**：用于版本控制和获取项目代码。

安装 GF CLI：
```bash
go install github.com/gogf/gf/v2/tool/gf@latest
```

确保 `gf` 命令可在终端中执行：
```bash
gf -v
```

**Section sources**
- [hack/hack.mk](file://hack/hack.mk#L1-L5)

## 依赖安装与构建

项目使用 `Makefile` 作为主要操作入口。构建二进制文件的命令如下：

```bash
make build
```

该命令会调用 `gf build -ew`，其中：
- `-e` 表示启用调试信息
- `-w` 表示启用竞争检测（race detection）

此命令将生成可执行文件，完成项目依赖的自动下载与编译。

**Section sources**
- [Makefile](file://Makefile#L5-L8)
- [hack/hack.mk](file://hack/hack.mk#L10-L13)

## 数据库初始化

项目使用 GoFrame 的 DAO（Data Access Object）机制进行数据库操作。数据库配置位于 `utility/config/database.go`，通过 `g.DB("v1")` 获取数据库实例。

初始化数据库表结构和迁移脚本：
```bash
make dao
```

该命令执行 `gf gen dao`，根据模型自动生成 DAO 层代码，包括：
- 数据表映射结构
- 基础增删改查方法
- 事务支持

数据库迁移记录表 `migrations` 用于跟踪数据库变更，确保多环境一致性。

**Section sources**
- [utility/config/database.go](file://utility/config/database.go#L1-L9)
- [internal/dao/internal/v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go#L31-L69)
- [internal/dao/internal/v_1_sys_config_dict.go](file://internal/dao/internal/v_1_sys_config_dict.go#L43-L90)
- [hack/hack.mk](file://hack/hack.mk#L22-L25)

## 项目启动

启动项目前，请确保配置文件已准备就绪。项目配置文件位于 `manifest/config/config.yaml`。

使用以下命令启动服务：
```bash
make run
```

> **注意**：`Makefile` 中未直接定义 `run` 命令，但 `gf` 工具默认支持 `gf run` 启动主程序。您也可直接执行：
> ```bash
> go run main.go
> ```

服务启动后，默认监听端口为 `12401`，可通过 `docker-compose.yml` 查看端口映射配置。

**Section sources**
- [main.go](file://main.go#L1-L50)
- [manifest/docker/docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L18)

## Hello World 示例：调用基础 API

项目提供健康检查 API 作为最简单的测试端点。

1. 确保服务已成功启动
2. 使用 `curl` 发起请求：

```bash
curl http://localhost:12401/monitor/v1/healthcheck
```

预期返回：
```json
{
  "code": 0,
  "message": "OK",
  "data": {
    "status": "healthy"
  }
}
```

该接口由 `api/monitor/v1/heathcheck.go` 定义，通过 `monitor` 模块注册路由，用于验证服务是否正常运行。

**Section sources**
- [api/monitor/v1/heathcheck.go](file://api/monitor/v1/heathcheck.go)
- [internal/controller/monitor/monitor_v1_health_check.go](file://internal/controller/monitor/monitor_v1_health_check.go)

## 常见问题排查指南

### 1. `gf` 命令未找到
**问题**：执行 `make build` 时报错 `gf: command not found`  
**解决方案**：确保已安装 GF CLI 并将其路径加入 `PATH` 环境变量：
```bash
export PATH=$PATH:$(go env GOPATH)/bin
```

### 2. 数据库连接失败
**问题**：启动时报错 `failed to connect database`  
**解决方案**：检查 `manifest/config/config.yaml` 中的数据库配置项，确保主机、端口、用户名、密码正确。

### 3. 端口被占用
**问题**：服务无法启动，提示端口 `12401` 已被占用  
**解决方案**：修改 `docker-compose.yml` 中的端口映射，或终止占用进程：
```bash
lsof -i :12401
kill -9 <PID>
```

### 4. 依赖下载失败
**问题**：`go mod download` 失败，无法拉取外部依赖  
**解决方案**：配置国内代理：
```bash
go env -w GOPROXY=https://goproxy.cn,direct
```

### 5. DAO 代码未生成
**问题**：执行 `make dao` 无输出或报错  
**解决方案**：确保项目根目录存在 `model` 定义文件，并检查 `gf` 版本是否兼容。

**Section sources**
- [hack/hack.mk](file://hack/hack.mk#L10-L74)
- [manifest/docker/docker-compose.yml](file://manifest/docker/docker-compose.yml#L1-L18)
- [utility/config/database.go](file://utility/config/database.go#L1-L9)

## 总结

通过本指南，您已成功完成 `kami_backend` 项目的环境搭建、构建、数据库初始化与服务启动，并验证了基础 API 的可用性。项目通过 `Makefile` 统一管理常用命令，结合 GoFrame 生态工具链，极大提升了开发效率。建议后续查阅 `api/` 目录下的各模块接口文档，深入了解业务逻辑实现。