Fork代码就能玩chinese-poetry-api开发者指南Makefileair热重载gqlgen代码生成【免费下载链接】chinese-poetry-api 诗泉高性能中国古诗词 API 服务项目地址: https://gitcode.com/gh_mirrors/ch/chinese-poetry-api本文是一份 chinese-poetry-api 开发者指南面向想 Fork 并二次开发这个收录近 40 万首古诗词的 Go 高性能 API 服务的新手讲透 Makefile 常用命令、air 热重载的秒级调试玩法以及 gqlgen 代码生成的标准流程帮你在本地快速跑起项目并贡献代码。这个项目同时提供 REST 和 GraphQL 双接口内置全文搜索、简繁双语、IP 限流等能力。对开发者来说仓库里已经把构建、测试、代码生成全部收敛到几条 make 命令里本地开发体验非常好。下面按跑起来 → 高效改代码 → 加接口 → 避坑的顺序讲。如何克隆 chinese-poetry-api 仓库并初始化开发环境一键克隆仓库注意诗词数据 submodule诗词原始数据放在poetry-data目录是一个 Git submodule见 .gitmodules所以克隆时必须带上子模块参数否则后续处理数据时会发现目录是空的git clone --recurse-submodules --depth1 https://gitcode.com/gh_mirrors/ch/chinese-poetry-api如果仓库已经克隆过可以单独补拉数据git submodule update --init --depth 1安装依赖并查看命令清单项目要求 Go 1.25见 go.mod克隆完成后两条命令即可make deps # 下载依赖并固定 gqlgen 工具版本 make help # 按分类列出全部可用命令make help是这份 Makefile 精心设计的默认入口会把构建、开发、测试、代码质量、Docker、发布命令分门别类打印出来比翻文档快得多。Makefile 命令速查表一键构建、测试与运行服务开发中 90% 的操作对应下面这张表建议直接收藏类别命令作用帮助make help按分类显示全部命令默认目标构建make build构建build/processor和build/server两个二进制构建make clean清理构建产物和数据库文件数据make process-data把poetry-data的 JSON 数据并行处理进 SQLite 数据库运行make run-server构建并启动 API 服务默认 1279 端口测试make test运行全部单元测试测试make coverage生成 HTML 测试覆盖率报告测试make bench/make fuzz基准测试 / 模糊测试如简繁转换、词牌分类质量make fmt/make lint/make tidy格式化、静态检查、整理依赖容器make docker-build/make docker-run构建镜像 / 用 docker-compose.yml 起容器发布make release v1.2.3校验版本号后创建 tag支持 GPG 签名两个容易忽略的细节Makefile 里统一带了CGO_ENABLED1和sqlite_fts5构建标签见 Makefile这是全文搜索FTS5能用的前提。所以永远走 make 命令构建别手动go build否则搜索功能会悄悄失效。本地完整跑通服务的三步走make build→make process-data→make run-server数据库会生成到data/poetry.db简体 繁体双表。air 热重载安装步骤保存代码自动重启改完 internal/api/rest/handler/ 里的 REST 处理器后不想手动重启仓库的make dev目标Makefile已经内置了热重载逻辑安装了 airmake dev直接启动 air保存文件 → 自动重新编译 → 自动重启服务全程秒级未安装 air终端会打印安装提示并自动回退到make run-server的普通模式。安装 air 后进入开发闭环一边跑make dev一边用 requests.http 里现成的请求集合健康检查、搜索、随机诗词、GraphQL 查询等验证改动保存即生效。make devgqlgen 代码生成流程改 GraphQL 接口的标准姿势这个项目的 GraphQL 接口基于 gqlgen 生成核心原则只改 schema 和 resolver永不手改生成文件。整个链条如下步骤文件你做什么1internal/graph/schema.graphqls定义 GraphQL 类型、查询与参数唯一的接口契约入口2gqlgen.yml代码生成配置schema 位置、输出位置、autobind复用database包的模型3命令行执行make graphql-gen触发 gqlgen 生成4internal/graph/generated/generated.go、internal/graph/model/models_gen.go自动生成的可执行 Schema 与数据模型不要手改5internal/graph/schema.resolvers.go手动实现各 Resolver 的业务逻辑查库、统计等6internal/graph/resolver.goResolver 的依赖注入入口持有*database.DB与*database.Repository几个值得学习的工程细节autobind 复用现有模型gqlgen.yml 声明自动绑定internal/database包GraphQL 类型会直接映射到已有的数据库模型避免生成一堆重复 struct工具依赖锁定tools/tools.go 通过 build tag 把 gqlgen 固定为工具依赖go mod tidy不会把它从 go.mod 里删掉——这是 Go 项目的通用技巧本地调试加分项把 config.yaml 中graphql.playground改为true服务启动后会多出一个/playground网页调试面板由 cmd/server/main.go 挂载。常见问题排查清单搜索接口报错或结果异常大概率是绕开 make 手动构建丢了sqlite_fts5标签。用make clean make build重来一次。make dev没有热重载air 未安装按终端提示安装后重试。go mod tidy后构建 GraphQL 报错检查 tools/tools.go 是否被误删它负责固定 gqlgen 工具依赖。服务启动提示没有数据库先执行make process-data生成data/poetry.db容器场景则无需处理scripts/startup.sh 会自动下载并校验数据库文件。/playground打不开config.yaml 里graphql.playground默认是false开发时改为true即可。想压测一下自己的改动tests/load/ 内置了 k6 脚本含安全、极限、尖峰三种档位跑完process-data后直接可用。小结Fork 这个仓库后你的开发主线其实就四条命令make help # 不知道干什么时先看这里 make process-data # 第一次本地准备数据 make dev # 日常air 热重载开发 make graphql-gen # 改了 schema.graphqls 之后Makefile 收敛了构建细节air 省掉了重启等待gqlgen 把 GraphQL 接口的改契约 → 生成 → 实现流程变得可预期。把这三件套跑顺再结合 tests/load/README.md 和 Makefile 的命令说明就可以愉快地给诗泉贡献代码了 【免费下载链接】chinese-poetry-api 诗泉高性能中国古诗词 API 服务项目地址: https://gitcode.com/gh_mirrors/ch/chinese-poetry-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考