跳至主要內容

AI工程师开源贡献：如何给Spring AI提交第一个PR

老张2026/4/30大约 8 分钟

AI工程师开源贡献：如何给Spring AI提交第一个PR

适读人群：想参与开源项目、给简历加分的Java工程师 阅读时长：约15分钟 文章价值：从找Issue到PR合并，完整流程 + 避坑指南

先说一件真实的事

去年有个读者，在公司工作三年，技术扎实，但简历上全是"负责xxx系统开发"这种描述，没有任何开源贡献。他在面试某互联网大厂的AI工程师岗位时，面试官问他："你有没有参与过开源项目？" 他只能说没有。

面试没过，他找我复盘时有点沮丧。我说："开源贡献不是大神专属，任何人都可以贡献，而且Spring AI恰好是个非常适合入门的项目。"

两个月后，他在Spring AI的GitHub上提交了3个PR，2个已经合并。简历上多了一行"Spring AI Contributor"。下一次面试，这一行字让话题多谈了10分钟。

今天就把完整流程写出来。

为什么选 Spring AI 作为入门项目

不是所有开源项目都适合新人贡献，Spring AI 有几个特点让它很适合：

特点说明
Java生态对Java工程师天然友好，不需要学新语言
项目年龄短2023年才开始，代码不复杂，文档不完善的地方多
维护活跃Pivotal团队在积极维护，Issue/PR回复快（通常1-3天）
功能覆盖广LLM/RAG/向量数据库/Agent，任何一块都能找到贡献点
文档缺口大文档永远追不上代码，写文档PR极易合并

开源贡献的四种类型

从简单到复杂：

第一个PR强烈建议从文档或测试开始，不要上来就挑战新功能。原因：

  1. 合并概率高（几乎100%）
  2. 熟悉贡献流程（Fork/PR/Review流程一样）
  3. 建立信任（维护者会认识你）

找到贡献机会

方法1：找带有"good first issue"标签的Issue

访问：https://github.com/spring-projects/spring-ai/issues?q=label%3A"good+first+issue"

这些Issue是维护者专门标记出来给新人做的，通常范围明确，难度适中。

方法2：在使用中发现问题

这是最自然的方式。你按文档做了某个功能，发现：

  • 文档步骤有错误或不完整
  • 示例代码无法运行
  • 某个API行为和文档描述不一致

这些都是绝好的贡献机会。

方法3：看GitHub最近的commit，找补充空间

# Clone项目，看最近的改动
git log --oneline -20

新功能合并进来后，往往缺少：

  • 对应的单元测试
  • 集成测试
  • Javadoc
  • 文档说明

这些都是PR素材。

完整贡献流程

第一步：Fork 和本地环境搭建

# 1. 在GitHub上Fork spring-ai到自己账号

# 2. Clone自己的Fork
git clone https://github.com/你的用户名/spring-ai.git
cd spring-ai

# 3. 添加上游仓库
git remote add upstream https://github.com/spring-projects/spring-ai.git

# 4. 创建工作分支（命名规范：类型/简短描述）
git checkout -b docs/fix-pgvector-setup-guide
# 或者
git checkout -b fix/token-splitter-npe
# 或者
git checkout -b feat/add-redis-vector-store

# 5. 构建项目（确保环境正常）
./mvnw clean compile -DskipTests

第二步：修改代码

以修复文档为例，找到文档文件修改：

# Spring AI文档在 docs/ 目录下（Antora格式）
ls docs/src/main/antora/modules/ROOT/pages/

# 修改后检查格式
# AsciiDoc格式，注意缩进和代码块语法

以添加测试为例：

// 假设我们给 TokenTextSplitter 补充一个边界情况测试
// 文件位置：spring-ai-core/src/test/java/.../TokenTextSplitterTests.java

@Test
void testSplitEmptyDocument() {
    // 测试空文档的处理（之前可能没有这个测试）
    TokenTextSplitter splitter = TokenTextSplitter.builder()
        .withDefaultChunkSize(100)
        .build();
    
    Document emptyDoc = new Document("", Map.of("id", "test-empty"));
    List<Document> result = splitter.apply(List.of(emptyDoc));
    
    // 空文档应该返回空列表，而不是抛出异常
    assertThat(result).isEmpty();
}

@Test
void testSplitDocumentWithOnlyWhitespace() {
    TokenTextSplitter splitter = TokenTextSplitter.builder()
        .withDefaultChunkSize(100)
        .withMinChunkLengthToEmbed(5)
        .build();
    
    Document whitespaceDoc = new Document("   \n\n   ", Map.of("id", "test-ws"));
    List<Document> result = splitter.apply(List.of(whitespaceDoc));
    
    // 全是空白的文档也应该返回空列表
    assertThat(result).isEmpty();
}

第三步：运行本地测试

# 运行你修改涉及的模块测试
./mvnw test -pl spring-ai-core -Dtest=TokenTextSplitterTests

# 确保所有测试通过
./mvnw verify -pl spring-ai-core

# 代码格式检查（Spring AI使用Checkstyle）
./mvnw checkstyle:check

注意：Spring AI有一些测试需要真实的API Key，跑CI时会跳过，本地也可以跳过：

# 跳过需要外部服务的集成测试
./mvnw test -pl spring-ai-core -Dskip.integration.tests

第四步：提交代码

Spring AI 使用约定式提交（Conventional Commits）：

# 格式：类型(范围): 描述
git commit -m "docs(vector-stores): fix pgvector setup instructions

The existing setup guide had incorrect Docker command for PgVector.
Updated to use the correct image tag and added missing volume mount.

Fixes: #1234"

# 类型说明：
# feat: 新功能
# fix: Bug修复
# docs: 文档
# test: 测试
# refactor: 重构
# chore: 构建/工具链

第五步：创建 PR

Push到自己的Fork后，在GitHub创建PR。PR描述模板（Spring AI通常有PR Template）：

## What does this PR do?
修复了PGVector安装文档中错误的Docker命令，并补充了缺失的volume挂载说明。

## Why is it needed?
用户按照原有文档操作无法正常启动PGVector容器，会导致连接失败。

## Related Issues
Fixes #1234

## How to test
1. 按照更新后的文档步骤执行
2. 验证PGVector容器正常启动
3. 运行 `spring-ai-pgvector-store` 模块的集成测试

## Checklist
- [x] 代码符合Spring AI的代码风格
- [x] 添加了对应的测试
- [x] 更新了相关文档
- [x] 提交信息符合约定式提交规范

Code Review：怎么应对维护者的意见

PR提交后，维护者可能会要求修改。常见要求：

意见类型应对方法
代码风格不符合看项目现有代码，对齐风格；跑一下Checkstyle
测试覆盖不足补充边界情况的测试用例
功能设计问题礼貌讨论，给出你的考量，接受合理建议
需要拆分PR把大PR拆成多个小PR，每个只做一件事
要求补文档在docs/目录下补充对应的说明

重要：不要把维护者的审查意见当批评，他们是在帮你提高代码质量。保持礼貌、积极回应，这些互动都在建立你在社区的信誉。

一个真实的贡献示例

下面是一个真实可提交的小贡献：给 VectorStore 的 similaritySearch 增加参数校验：

// 在 AbstractVectorStoreBuilder 或 VectorStore 实现类中
// 增加输入参数校验，防止空查询导致奇怪的错误

public List<Document> similaritySearch(SearchRequest request) {
    // 新增：参数校验，提供更友好的错误信息
    Assert.notNull(request, "SearchRequest must not be null");
    Assert.hasText(request.getQuery(), "Search query must not be empty");
    Assert.isTrue(request.getTopK() > 0, 
        "TopK must be greater than 0, but was: " + request.getTopK());
    Assert.isTrue(request.getSimilarityThreshold() >= 0.0 && request.getSimilarityThreshold() <= 1.0,
        "Similarity threshold must be between 0.0 and 1.0");
    
    return doSimilaritySearch(request);
}

对应的测试：

@Test
void shouldThrowExceptionWhenQueryIsEmpty() {
    assertThatThrownBy(() -> 
        vectorStore.similaritySearch(SearchRequest.query("")))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("query must not be empty");
}

@Test
void shouldThrowExceptionWhenTopKIsZero() {
    assertThatThrownBy(() ->
        vectorStore.similaritySearch(
            SearchRequest.query("test").withTopK(0)))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("TopK must be greater than 0");
}

这种PR：代码量不大，但有明确的价值（改善错误信息），有完整测试，很容易合并。

常见坑

  1. PR太大：一个PR改了20个文件，维护者看着就头疼。原则：一个PR只做一件事。
  2. 没有测试：Spring AI对测试要求比较严，特别是功能性变更。
  3. 没有同步upstream：PR里有很多merge conflict，说明没有及时rebase。
  4. 提交信息不规范：Spring AI的CI会检查提交信息格式。
  5. 直接push到main：应该在feature分支上工作。
# 定期同步upstream，避免冲突
git fetch upstream
git rebase upstream/main

小结

给 Spring AI 提第一个 PR 的最短路径：

  1. 找一个"good first issue"或者在使用中发现的文档问题
  2. Fork → feature分支 → 修改 → 测试 → PR
  3. 写清楚PR描述，认真回应Review意见
  4. 合并后，把这段经历加到简历上

开源贡献不是大神专属，它是一个反复练习的过程。第一个PR可能只改了三行文档，但流程走通了，后面的就越来越顺。

那个读者后来告诉我，他第一个PR是修复了一个示例代码里的typo（一个变量名拼错了），三天后就合并了。他说："看到Merged的那一刻，有点上头。"这种感觉，值得去体验一次。

编辑此页
最近更新:
贡献者: xiaozhangge