OpenFrame OSS Lib 贡献者指南:代码规范、PR 流程与 OpenMSP 社区协作全攻略
OpenFrame OSS Lib 贡献者指南:代码规范、PR 流程与 OpenMSP 社区协作全攻略
OpenFrame OSS Lib 是 OpenFrame 平台的核心后端共享库集合(shared libraries):一个包含 Java 21 / Spring Boot 模块、React 前端组件库和 Rust 设备代理的 Maven 多模块 monorepo。本文是一份面向新手的 OpenFrame OSS Lib 贡献者指南,带你快速掌握项目的代码规范、分支与提交信息格式、PR 评审流程,以及 OpenMSP 社区协作方式,从环境搭建到提交第一个 PR 一次讲透。
项目速览:一个仓库,三种语言 🧭
在动手写代码之前,先搞清楚"要往哪贡献"。OpenFrame OSS Lib 不是可独立部署的服务,而是一组可独立版本化的 Maven 构件,供 OpenFrame 各业务服务复用。仓库按职责拆分为清晰的模块:
| 语言 / 技术栈 | 所在模块 | 构建工具 |
|---|---|---|
| Java 21 + Spring Boot 3.3 | openframe-api-service-core/、openframe-gateway-service-core/、openframe-data-mongo-sync/ 等 30+ 模块 | Maven 3.9+ |
| TypeScript + React | openframe-frontend-core/(UI 组件库,含 Storybook) | Node.js 18+ / npm |
| Rust | clients/openframe-client/(跨平台设备代理) | Cargo(Tokio 异步运行时) |
📌 建议先通读 README.md 中的 Module Summary 和 docs/getting-started/first-steps.md,对模块分层(网关 → 鉴权 → API → 数据层)建立整体印象,再选择自己最熟悉的模块切入。
开始前的环境准备:5 分钟跑通首次构建 ⚡
贡献共享库的第一步是本地能构建、能跑测试。官方前置清单见 docs/getting-started/prerequisites.md:
- 必装:JDK 21、Maven 3.9+、Git 2.x+、Docker 24+(集成测试依赖 Testcontainers)
- 按需:Node.js 18+(改前端时)、Rust stable(改 Rust 代理时)
- 推荐:IntelliJ IDEA(需启用 Lombok 插件与注解处理器)
拿到代码并完成首次构建只需三步:
# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/op/openframe-oss-lib
cd openframe-oss-lib
# 2. 构建全部模块(先跳过测试,速度更快)
mvn clean install -DskipTests
# 3. 确认构件已装入本地 Maven 仓库
mvn dependency:resolve -DincludeArtifactIds=openframe-core
完整步骤与单模块构建技巧(-pl / -am 参数)见 docs/getting-started/quick-start.md,本地联调环境参考 docs/development/setup/local-development.md。
代码规范速查:Java、前端与 Rust 三套标准 ✅
贡献者指南的完整原文在 CONTRIBUTING.md 和 docs/development/contributing/guidelines.md。核心约定一张表看懂:
Java(绝大多数模块)
| 约定 | 标准 |
|---|---|
| 缩进 / 行宽 | 4 空格(禁用 Tab);最长 120 字符 |
| 导入 | 禁止通配符导入(import com.example.*) |
| 样板代码 | 优先 Lombok:@Data、@Builder、@RequiredArgsConstructor、@Slf4j |
| 依赖注入 | 构造器注入(@RequiredArgsConstructor),避免字段 @Autowired |
| 日志 | log.info() / debug() / error(),永不使用 System.out.println |
| 空值 | 服务层可空返回值优先 Optional<T> |
| 异常 | 继承 openframe-exception/ 提供的 BaseException 体系 |
TypeScript / React(openframe-frontend-core)
Prettier 格式化 + ESLint 自动修复(保存时触发);组件统一用函数式 + React Hooks;样式用 Tailwind 工具类;库内一律相对路径导入。
Rust(clients/openframe-client)
提交前执行 cargo fmt;cargo clippy -- -D warnings 必须零警告;生产代码禁止 .unwrap(),用 anyhow 或领域 Result<T, E> 处理错误。
💡 一个高信号判断标准:评审时最常被拒的 PR,几乎都是"手工 getter/setter + 字段注入 + 通配导入"这类与 Lombok 约定相悖的写法。
分支与提交信息:用 Conventional Commits 写"自解释"日志 📝
分支命名:小写 + 连字符
| 类型 | 模式 | 示例 |
|---|---|---|
| 新功能 | feat/<short-description> |
feat/add-script-tagging |
| 修 Bug | fix/<short-description> |
fix/tenant-query-filter |
| 重构 | refactor/<short-description> |
refactor/notification-service |
| 文档 | docs/<short-description> |
docs/update-arch-overview |
| 杂项 | chore/<short-description> |
chore/bump-spring-boot-version |
提交信息:type(scope): 简短描述
遵循 Conventional Commits 规范,scope 用模块名或领域名。常用类型:feat(新功能)、fix(修 Bug)、refactor(无行为变更的重构)、test(测试)、docs(文档)、chore(构建/依赖)、perf(性能)、style(格式)。
feat(gateway): add origin sanitizer filter
fix(stream-processing-core): prevent overwriting terminal execution states
chore(deps): bump testcontainers to 1.21.4
第二条提交信息值得细看:正文用两三行解释了"为什么改"(Kafka 重复消息引发的竞态条件),这正是评审者最想看到的信息密度。
⚠️ 版本号由 CI 通过
flatten-maven-plugin管理(开发态默认999-SNAPSHOT),请勿手动修改源码中的版本号。
提交 PR 的完整流程:从检查清单到评审 📤
开 PR 前的自检清单
- [ ] 非平凡改动已在 OpenMSP Slack 中先行讨论
- [ ] 已 rebase 到最新
main分支 - [ ] 本地
mvn test全部通过;相关模块的mvn verify集成测试通过 - [ ] 代码已格式化(Java 用 IDE 自动格式化;前端
npm run format;Rustcargo fmt) - [ ] Diff 中没有任何密钥、凭据或环境相关硬编码
- [ ] 新增公开 API 附带 Javadoc
PR 描述与评审重点
PR 描述按官方模板分四部分:Summary(做什么、为什么)→ Changes(增删改清单)→ Testing(单测/集成测试/手动验证)→ Related(Slack 讨论线索)。
评审者(Reviewers)会重点核对以下红线:
- 新的 MongoDB 仓库必须继承
TenantAwareRepository(租户隔离) - 租户维度数据禁止直接使用
MongoTemplate - 敏感字段必须经
EncryptionService加密落库 - 异常处理走
openframe-exception体系 - 测试覆盖"快乐路径 + 至少一条错误路径"
- 对外 API 端点补齐 OpenAPI 注解
测试要求:三层测试金字塔怎么跑 🧪
测试策略全貌见 docs/development/testing/README.md:
| 层级 | 工具 | 说明 |
|---|---|---|
| 单元测试 | JUnit 5 + Mockito | 隔离业务逻辑,快、无 I/O |
| 集成测试 | Testcontainers + JUnit 5 | 启动真实 MongoDB / NATS / Redis |
| 端到端 | openframe-test-service-core/ | 覆盖完整平台 API |
# 单模块单元测试
mvn test -pl openframe-api-service-core
# 集成测试(需先启动 Docker)
mvn verify -pl openframe-data-mongo-sync
写测试的四条铁律:一个测试只验证一个行为、方法名要会说话(shouldReturnEmptyListWhenNoScriptsExist 优于 test1)、遵循 AAA(Arrange–Act–Assert)、单元测试中 Mock 外部依赖并覆盖负路径(null 入参、未找到、权限失败)。
模块与依赖管理:新增模块和升级依赖的正确姿势 🏗️
新增库模块五步走:在仓库根目录创建模块目录 → 编写继承父 POM 的 pom.xml(groupId 为 com.openframe.oss,版本写 ${revision})→ 把模块加入父 pom.xml 的 <modules> 与 <dependencyManagement> → 为模块撰写 README.md。
升级依赖只需记住一句话:所有版本只改父 POM,子模块 POM 不写版本号,改完跑 mvn verify 全量验证。
安全红线:贡献者的 5 条铁律 🔒
安全规范详见 docs/development/security/README.md:
- 永不提交密钥——凭据、API Key、连接字符串一律不入库
- 租户数据只用
TenantAwareRepository,禁用裸MongoTemplate - 敏感字段用
EncryptionService加密后再写 MongoDB - 所有 DTO 输入使用 Jakarta Bean Validation 注解做校验
- 租户身份只从 JWT 解析,绝不信任请求体/查询参数里的
tenantId
⛔ 发现安全漏洞时,不要公开提 Issue 或在 PR 中描述——请通过 OpenMSP Slack 私聊维护者。
OpenMSP 社区协作:Slack 先行,PR 在后 🤝
OpenFrame 的协作模式与大多数开源项目不同:项目不使用 GitHub Issues / Discussions,所有协调都在 OpenMSP Slack 社区进行。
- 先聊后写:Bug、改进或功能想法,先在 Slack 发起讨论再动手,避免重复劳动、对齐平台路线图
- 小改动直接上:错别字、明显 Bug 修复等低风险改动可直接提交 PR
- 求助渠道:Slack 社区 + 仓库内置文档体系(docs/README.md 汇总了入门、架构、测试与安全全部指南)
新手贡献路线图(TL;DR)🚀
- 读 docs/getting-started/introduction.md 理解项目定位
- 按 docs/getting-started/prerequisites.md 配好环境,
mvn clean install -DskipTests验证构建 - 在 openframe-core/ 等基础模块找一个
docs或fix类小问题练手 - 按
feat/fix/规范建分支,Conventional Commits 写提交信息 - 自检清单逐条过 → 按模板写 PR 描述 → 提交并在 Slack 同步进展
📄 最后提醒:你的每一份贡献都将以项目原有许可协议(见 LICENSE.md)发布,提交即代表同意该条款。祝你在 OpenFrame OSS Lib 的共享库世界里贡献愉快!