OpenFrame OSS Lib 贡献者指南:代码规范、PR 流程与 OpenMSP 社区协作全攻略

原创2026-10-14 12:49:261,344 阅读

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;Rust cargo fmt)
  • [ ] Diff 中没有任何密钥、凭据或环境相关硬编码
  • [ ] 新增公开 API 附带 Javadoc

PR 描述与评审重点

PR 描述按官方模板分四部分:Summary(做什么、为什么)→ Changes(增删改清单)→ Testing(单测/集成测试/手动验证)→ Related(Slack 讨论线索)。

评审者(Reviewers)会重点核对以下红线:

  1. 新的 MongoDB 仓库必须继承 TenantAwareRepository(租户隔离)
  2. 租户维度数据禁止直接使用 MongoTemplate
  3. 敏感字段必须经 EncryptionService 加密落库
  4. 异常处理走 openframe-exception 体系
  5. 测试覆盖"快乐路径 + 至少一条错误路径"
  6. 对外 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:

  1. 永不提交密钥——凭据、API Key、连接字符串一律不入库
  2. 租户数据只用 TenantAwareRepository,禁用裸 MongoTemplate
  3. 敏感字段用 EncryptionService 加密后再写 MongoDB
  4. 所有 DTO 输入使用 Jakarta Bean Validation 注解做校验
  5. 租户身份只从 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)🚀

  1. 读 docs/getting-started/introduction.md 理解项目定位
  2. 按 docs/getting-started/prerequisites.md 配好环境,mvn clean install -DskipTests 验证构建
  3. 在 openframe-core/ 等基础模块找一个 docs 或 fix 类小问题练手
  4. 按 feat/ fix/ 规范建分支,Conventional Commits 写提交信息
  5. 自检清单逐条过 → 按模板写 PR 描述 → 提交并在 Slack 同步进展

📄 最后提醒:你的每一份贡献都将以项目原有许可协议(见 LICENSE.md)发布,提交即代表同意该条款。祝你在 OpenFrame OSS Lib 的共享库世界里贡献愉快!

登录后查看全文
openframe-oss-lib