FAQ - 常见问题
这里汇总了 Go-Spring 全局性的常见问题。如果你在找特定模块的问题，请查看对应模块文档：
项目整体
Q: Go-Spring 是什么？设计理念是什么？
A: Go-Spring 是一个继承了 Spring 理念的 Go 语言依赖注入框架，核心设计理念是：
- 保持 Go 原生风格：不强行模仿 Java Spring，用 Go 的方式解决 Go 的问题
- 问题早发现早解决：所有依赖解析都在启动期完成，运行时不需要容器介入
- 显式优于隐式：一切依赖清晰可见，没有魔法，避免难以调试的意外
- 条件互斥优于覆盖：不允许同名 Bean 隐式覆盖，用条件匹配决定哪个生效
- 简洁就是美：不做过度设计，只解决真正需要解决的问题
Q: Go-Spring 和其他 Go 依赖注入框架（Wire、dig、fx）有什么区别？
A:
| 特性 | Go-Spring | Wire | dig | fx |
|---|---|---|---|---|
| 依赖解析时机 | 启动期反射 | 编译期代码生成 | 运行时反射 | 运行时反射 |
| 单例默认 | ✓ | - | ✓ | ✓ |
| 条件注册 | ✓ | - | ✗ | ✗ |
| 配置绑定 | 内置 | 不内置 | 不内置 | 不内置 |
| 循环依赖支持 | 字段注入自动处理 | 不支持 | ✗ | ✗ |
| 批量注册 Group | ✓ | - | ✗ | ✗ |
Go-Spring 选择启动期反射的路线，这带来几个好处：
- 不需要额外的代码生成步骤，开发流程更简洁
- 支持条件注册，支持根据配置动态决定哪些 Bean 生效
- 自动处理循环依赖（字段注入方式）
- 内置配置绑定，不需要第三方库
如果你偏好编译期代码生成，Wire 是很好的选择。如果你喜欢 Go-Spring 的设计理念，那么它会非常顺手。
Q: 为什么叫 Go-Spring，和 Java Spring 是什么关系？
A: Go-Spring 继承了 Spring 框架的控制反转和依赖注入核心思想，但不是 Java Spring 的Go语言重实现。
我们坚持 Go 原生设计哲学，不会把 Java Spring 的概念照搬到 Go 中来，很多设计决策和 Java Spring 不一样，比如：
- Go-Spring 不支持运行时动态获取 Bean，坚持启动期一次性解决
- Go-Spring 不允许 Bean 覆盖，坚持条件互斥
- Go-Spring 要求接口显式导出，不做自动推导
所以它继承了理念，但不是移植，是 Go 方式的重新设计。
Q: Go-Spring 现在稳定吗？可以用于生产环境吗？
A: Go-Spring 已经经过多年迭代，核心功能稳定，已经在生产环境中使用。
入门相关
Q: 怎么从零开始创建一个 Go-Spring 项目？
A: 推荐从 starter 模板开始：
# 克隆模板
git clone https://github.com/go-spring/starter.git my-project
cd my-project
# 拉取依赖
go mod tidy
# 运行
go run main.go模板已经配置好了最常用的 starter，你可以直接在上面开发。
Q: 推荐的项目目录结构是什么样的？
A: Go-Spring 没有强制要求项目结构，推荐遵循 Go 社区惯例：
my-project/
├── main.go # 入口文件
├── go.mod # 依赖管理
├── config/ # 配置类
├── service/ # 业务服务
├── controller/ # HTTP 控制器
├── repository/ # 数据访问层
└── model/ # 数据模型基本原则：按领域分层，保持清晰依赖。
Q: 哪里可以找到完整的示例项目？
A: 示例项目汇总在 go-spring/examples，你可以参考。
开发相关
Q: 怎么运行测试？
A: 和 Go 原生完全一样：
go test ./...详细测试用法请参考 07-testing.md。
Q: 怎么参与贡献？
A: 欢迎贡献！
- 报告 Issue: github.com/go-spring/go-spring/issues
- 提交 Pull Request: fork 仓库后修改，提交 PR 即可
- 贡献前请阅读仓库根目录的
CODING_STYLE.md了解编码规范
Q: 为什么我的 Bean 没有被注册？
A: 常见原因：
- 忘记在
init()中调用gs.Provide注册 - 条件不满足，被条件裁剪掉了，检查你的条件配置
- Bean 没有被依赖，Go-Spring 是按需创建，未被依赖的 Bean 不会实例化（但仍然会注册）
Q: 为什么启动报错 "conflict: bean already registered"？
A: 出现这个错误说明有两个相同类型相同名称的 Bean 同时注册了。
解决办法：
- 如果确实需要两个实例，给它们分别设置
.Name("xxx")命名区分 - 如果是不同条件下应该只有一个生效，加上条件匹配（比如
OnProfiles） - 如果是测试中想覆盖，测试中的
ctx.Provide不会影响全局，所以可以放心覆盖
Go-Spring 不允许相同类型相同名称的 Bean 在同一个条件下共存，这是设计选择，避免隐式覆盖带来难以调试的问题。
性能相关
Q: Go-Spring 启动慢吗？运行时开销大吗？
A:
- 启动开销：所有依赖注入都在启动期完成，启动时间和 Bean 数量正相关，一般项目启动在几十毫秒级别
- 运行时开销：启动完成后会清理所有元数据，运行时没有额外开销，性能和手写代码一样
- 内存占用：只有你的 Bean 占用内存，容器本身在启动后几乎不占用内存
所以不用担心性能问题，Go-Spring 运行时非常轻量。
Q: 怎么优化启动速度？
A:
- 按需创建默认开启，未被依赖的 Bean 不会创建，节省时间
- 只注册你真正需要的 Bean，避免注册大量不用的代码
- 拆分模块，使用条件注册，只在需要时启用
关于这个文档
这是一个不断完善的文档，如果你有新的问题，欢迎提交 Issue 补充。