设计理念

Firefly 的设计遵循以下核心原则，旨在平衡开发的灵活性与架构的规范性。

1. 协议优先 (Schema-First)

在微服务架构中，API 契约是服务间协作的基石。Firefly 坚持使用 Protobuf (Protocol Buffers) 作为接口定义语言 (IDL)。

• 单一事实来源：所有的 API 定义、数据结构验证规则都定义在 .proto 文件中。
• 代码生成：通过 buf 等工具自动生成 Server Stub、Client SDK 和 DTO，避免手动编写重复代码。
• 语言无关：一份 Proto 定义可以同时生成 Go, Rust, TypeScript 等多种语言的代码，天然支持多语言生态。

2. 整洁架构 (Clean Architecture)

Firefly 的项目模板（如 go-layout）严格遵循整洁架构的分层原则，实现关注点分离。

• Biz 层（核心业务）：纯净的业务逻辑，不依赖任何外部实现（如数据库、HTTP 框架）。
• Data 层（数据适配）：负责数据的持久化和外部接口的调用，通过接口实现 Biz 层的需求。
• Service 层（应用服务）：负责处理网络请求（gRPC/HTTP），进行参数校验和 DTO 转换，编排 Biz 层逻辑。

这种设计使得业务逻辑高度可测试、易于维护，并且可以在不修改业务代码的情况下替换底层实现（例如将 MySQL 换成 MongoDB）。

3. 依赖注入 (Dependency Injection)

为了管理复杂的组件依赖关系，Firefly 提倡使用依赖注入模式。

• 显式依赖：组件所需的依赖（如数据库连接、配置对象）通过构造函数显式传入，而不是在内部隐式创建或通过全局变量获取。
• 编译期安全：在 Go 语言实现中，我们使用 Google Wire 进行编译期依赖注入，在代码编译阶段就能发现依赖缺失的问题，避免运行时错误。

4. 约定优于配置 (Convention over Configuration)

Firefly 提供了一套标准化的目录结构和命名规范。

• 统一目录：所有服务都采用相同的 internal/biz, internal/data 等目录结构。
• 统一配置：标准化的 bootstrap.json 引导配置，统一管理服务身份、业务端口、管理端口、sidecar-agent、日志和 telemetry 等启动参数。

这使得新加入的开发者能够快速上手任何一个基于 Firefly 构建的服务，无需花费大量时间熟悉项目结构。

5. 极简与可扩展

Firefly 的核心库保持轻量级，不强行绑定过多的第三方库。

• 模块化设计：日志、配置、注册发现和运行时治理都面向稳定契约，裸机 / IDC 可使用 Consul 适配层，云原生环境可切换到 K8s / Istio 运行时，业务代码不直接绑定底层 SDK。
• 代码透明：生成的代码（如 wire_gen.go）也是清晰可读的 Go 代码，没有黑魔法。

6. 单服务单仓库 (Repo-per-Service)

Firefly 倡导 单个服务单个仓库 的代码管理模式，不推荐使用大仓 (Monorepo)。

• 独立演进：每个服务拥有独立的版本控制、CI/CD 流程和依赖管理，避免“牵一发而动全身”。
• 公共库抽取：通用的业务逻辑、工具函数应抽取为独立的 SDK 或 Package（如 go-utils），以库的形式被各个服务引用。
• 边界清晰：物理上的仓库隔离强制划清了服务边界，减少了隐式的代码耦合。