用于快速构建项目的基础库.
本节专为 AI 助手（如 Claude、GPT 等）设计，帮助 AI 快速理解项目并提供开发协助。
AI 应优先阅读 AI_REFERENCE.md 而非扫描整个项目代码，在以下场景中：
| 场景 | 说明 |
|---|---|
| 快速开发任务 | 需要基于 zapp 创建新组件/插件/服务 |
| 接口查询 | 需要了解核心接口定义（IComponent、IPlugin、IService 等） |
| 架构理解 | 需要快速理解项目整体架构和生命周期 |
| 配置使用 | 需要了解配置加载方式、Apollo 配置或配置热加载 |
| 工具包使用 | 需要使用 pkg 下的序列化器、压缩器、工具函数等 |
| 代码生成 | 需要生成符合 zapp 规范的代码模板 |
以下场景 AI 仍应扫描具体代码文件：
仅在以下情况需要深入阅读源码:
- 调试具体问题时
- 实现高级定制功能时
- 文档信息不足以解决当前问题时
- 位置:
./AI_REFERENCE.md - 内容: 核心接口定义、架构概览、配置系统、工具包索引、开发指引、关键文件索引
- 目的: 让 AI 无需扫描整个代码仓库即可快速开发
如需构建完整业务项目，推荐使用 uapp，它封装了 zapp 并预置常用组件/插件和 Apollo 配置支持，且提供脚手架文档可按需求关键词快速定位工具。
推荐使用 uapp，它封装了 zapp 并预置常用组件、插件（pprof/otlp/apollo_provider 等）和 Apollo 配置支持，且提供脚手架文档方便 AI 快速生成项目。
直接使用 zapp：
app := zapp.NewApp("test")
app.Run()- 我们实现了一些插件, 可以在 这里 找到
- 这里 内置了一些 filter
- 我们实现了一些服务, 可以在 这里 找到
- 请转到 这里
初始化时添加 zapp.WithEnableDaemon() 选项, 构建后使用以下命令
./app文件
install [args] 安装服务, args 是运行时传递给 app 的参数
remove 移除服务
start 启动app
stop 停止app
status 查看运行状态
初始化时添加 zapp.WithHandler(...) 选项
BeforeInitializeHandler 在app初始化前
AfterInitializeHandler 在app初始化后
BeforeStartHandler 在app启动前
AfterStartHandler 在app启动后
BeforeExitHandler 在app退出前
AfterExitHandler 在app退出后
初始化时添加 zapp.WithCustomEnablePlugin(...) 选项, zapp 会根据返回值来决定开启和关闭哪些插件
zapp.WithCustomEnablePlugin(func(app core.IApp, plugins []core.PluginType) []core.PluginType {
if !app.GetConfig().HasFlag("my_plugin") {
plugins = append(plugins, "my_plugin")
}
return plugins
})初始化时添加 zapp.WithCustomEnableService(...) 选项, zapp 会根据返回值来决定开启和关闭哪些服务
zapp.WithCustomEnableService(func(app core.IApp, services []core.ServiceType) []core.ServiceType) Option {
if !app.GetConfig().HasFlag("api_service") {
services = append(services, "api")
}
return services
})core.ILogger 提供了 NewTraceLogger(ctx context.Context, fields ...zap.Field) ILogger 方法用于创建一个带链路id的 logger(前提是ctx中包含有效的span).
使用生成的log打印日志会带上链路id, 并且我们会根据不同的链路id输出不同的颜色.
core.ILogger 提供了 NewSessionLogger(fields ...zap.Field) ILogger 方法用于创建一个会话 logger.
使用会话logger打印日志会产生一个全局日志id, 并且我们会根据不同的全局日志id输出不同的颜色.
日志打印时可以将 ctx 传入, 如果 ctx 中包含 traceID 那么在日志输出中会带上 traceID. 示例 app.Info(ctx, "test")
初始化 > 用户操作 > 启动 > 退出
app := zapp.NewApp(...) > 生成BaseContext > 加载配置 > 初始化日志记录器 > 构建组件 > 构建插件 > 构建并初始化 filter > 构建服务
用户在这里对服务进行注入, 如注入插件, 注入服务等.
app.Run() > 启动插件 > 启动服务 > 启动内存释放任务 > 阻塞等待退出信号
app.Exit() 或收到退出信号 > 关闭BaseContext > 停止内存释放任务 > 关闭服务 > 关闭 filter > 关闭插件 > 释放组件资源 > 结束之前调用app.Run()的阻塞