Skip to main content

LangChain4j 学习路径测试代码库

版权归属于 LangChat Team
官网:https://langchat.cn

项目介绍

这是一个独立的 Java 项目,用于存放 LangChain4j 学习路径中所有文档涉及的测试代码和示例,让开发人员能够快速运行和测试 LangChain4j 的各种功能。

项目定位

  • 可运行性 - 所有代码都是完整的 Maven 项目,可以直接运行
  • 测试覆盖 - 每个学习文档都有对应的测试代码
  • 配置统一 - 使用 .env 文件统一管理配置
  • 快速上手 - 开发人员可以快速克隆并运行测试
  • 模块化设计 - 每个学习主题对应独立的测试模块

快速开始

前置要求

  • JDK 17+
  • Maven 3.9+

⚠️ 配置 API Key

在运行测试之前,必须先配置 API Key。本项目使用 .env 文件管理配置。

步骤 1:复制配置文件

步骤 2:编辑 .env 文件

配置优先级

配置按以下优先级加载(从高到低):
  1. 系统环境变量(最高优先级)
  2. .env.local 文件
  3. .env 文件
  4. 默认值(最低优先级)

使用系统环境变量

运行测试

运行示例

在 IntelliJ IDEA 中直接运行示例类的 main 方法,例如:
  • src/test/java/cn/langchat/learning/tutorial/introduction/HelloWorldExample.java

打印配置信息

项目结构

技术栈

核心框架

LangChain4j 依赖

可选依赖

配置说明

环境变量配置

支持以下配置项(通过 .env 文件或系统环境变量):

配置加载顺序

  1. 系统环境变量 - 优先级最高,用于 CI/CD 或特殊场景
  2. .env.local - 本地开发时覆盖 .env 配置
  3. .env - 默认配置文件
  4. 默认值 - 代码中的默认值

安全性

  • .env.env.local 已在 .gitignore
  • ✅ API Key 等敏感信息不会提交到版本控制
  • ✅ 日志输出自动遮盖敏感信息
  • ✅ 支持通过系统环境变量覆盖配置

测试覆盖

完整的文档列表请参考 docs/ 目录。

开发指南

添加新的测试

  1. src/test/java/cn/langchat/learning/tutorial/<文档编号>/ 创建测试包
  2. 使用 JUnit 5 和 Lombok 编写测试
  3. 使用 TestModelProvider 获取配置好的模型

代码规范

  • 使用 Lombok 注解减少样板代码(@Slf4j, @Data, @Builder 等)
  • 遵循 Java 命名规范
  • 测试方法使用 @DisplayName 添加中文描述
  • 使用 TestModelProvider.getChatModel() 获取模型实例

测试代码示例

配置获取示例

常见问题

Q1: 如何获取 API Key?

访问相应模型提供商的官网注册并创建 API Key:

Q2: 测试失败怎么办?

检查以下项目:
  1. ✅ API Key 是否在 .env 文件中正确配置
  2. ✅ 网络连接是否正常
  3. ✅ API 额度是否充足
  4. ✅ 查看日志中的错误信息

Q3: 如何切换到其他模型?

编辑 .env 文件中的模型配置:

Q4: 如何在本地覆盖配置?

创建 .env.local 文件,设置需要覆盖的配置项:

Q5: 为什么使用 .env 文件而不是系统环境变量?

使用 .env 文件的优点:
  • ✅ 配置集中管理,易于维护
  • ✅ 支持本地覆盖(.env.local)
  • ✅ 不同环境可以有不同的 .env 文件
  • ✅ 避免在 CI/CD 中硬编码配置
  • ✅ .env 文件被 .gitignore 忽略,安全可靠

项目特点

1. 环境配置管理

  • 使用 .env 文件统一管理配置
  • 支持多级配置覆盖(环境变量 > .env.local > .env)
  • 自动加载和类型转换
  • 敏感信息遮盖

2. 统一的模型提供者

  • TestModelProvider 提供统一的模型获取接口
  • EnvConfig 负责配置加载和管理
  • 测试代码无需关心配置细节

3. 模块化设计

  • 每个学习主题对应独立的测试包
  • 测试类和示例类分离
  • 工具类独立管理

4. 安全性

  • API Key 通过环境变量或 .env 文件管理
  • 敏感配置文件被 .gitignore 忽略
  • 日志输出自动遮盖敏感信息

参考资料

许可证

本项目版权归 LangChat Team 所有。

贡献指南

欢迎贡献代码、报告问题或提出改进建议!
Happy Learning! 🚀