danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/快速入门.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

6.1 KiB
Raw Blame History

快速入门

**本文档中引用的文件** - [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)

目录

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

简介

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

Section sources

开发环境配置

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

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

安装 GF CLI：

go install github.com/gogf/gf/v2/tool/gf@latest

确保 gf 命令可在终端中执行：

gf -v

Section sources

依赖安装与构建

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

make build

该命令会调用 gf build -ew，其中：

  • -e 表示启用调试信息
  • -w 表示启用竞争检测（race detection）

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

Section sources

数据库初始化

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

初始化数据库表结构和迁移脚本：

make dao

该命令执行 gf gen dao，根据模型自动生成 DAO 层代码，包括：

  • 数据表映射结构
  • 基础增删改查方法
  • 事务支持

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

Section sources

项目启动

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

使用以下命令启动服务：

make run

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

go run main.go

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

Section sources

Hello World 示例：调用基础 API

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

  1. 确保服务已成功启动
  2. 使用 curl 发起请求：
curl http://localhost:12401/monitor/v1/healthcheck

预期返回：

{
  "code": 0,
  "message": "OK",
  "data": {
    "status": "healthy"
  }
}

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

Section sources

常见问题排查指南

1. gf 命令未找到

问题：执行 make build 时报错 gf: command not found
解决方案：确保已安装 GF CLI 并将其路径加入 PATH 环境变量：

export PATH=$PATH:$(go env GOPATH)/bin

2. 数据库连接失败

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

3. 端口被占用

问题：服务无法启动，提示端口 12401 已被占用
解决方案：修改 docker-compose.yml 中的端口映射，或终止占用进程：

lsof -i :12401
kill -9 <PID>

4. 依赖下载失败

问题：go mod download 失败，无法拉取外部依赖
解决方案：配置国内代理：

go env -w GOPROXY=https://goproxy.cn,direct

5. DAO 代码未生成

问题：执行 make dao 无输出或报错
解决方案：确保项目根目录存在 model 定义文件，并检查 gf 版本是否兼容。

Section sources

总结

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