跳转至

开发指南

文档版本: 2.0.0 最后更新: 2026-06-15 Git 提交: 0f56b957 作者: JAiRouter Team

欢迎来到 JAiRouter 开发指南!本指南为开发者提供了完整的开发环境搭建、代码规范、测试策略和贡献流程。

快速开始

如果您是第一次参与 JAiRouter 开发,建议按以下顺序阅读:

  1. 架构说明 - 了解系统整体架构和设计原则
  2. 贡献指南 - 学习如何参与项目开发
  3. 测试指南 - 掌握测试策略和最佳实践
  4. 代码质量标准 - 遵循项目代码规范

开发环境要求

工具版本要求说明
Java17+必须,LTS 版本
Maven3.8+推荐使用项目内置 Maven Wrapper
Git2.20+版本控制
IDE-IntelliJ IDEA(推荐)或 Eclipse

核心开发流程

1. 环境准备

# 克隆项目
git clone https://github.com/Lincoln-cn/JAiRouter.git
cd jairouter

# 构建项目(中国用户推荐)
./mvnw clean package -Pchina

# 运行测试
./mvnw compiler:compile compiler:testCompile surefire:test

2. 开发规范

  • 遵循 代码质量标准 中的编码规范
  • 使用 Checkstyle 和 SpotBugs 进行代码质量检查
  • 确保测试覆盖率不低于 80%

3. 提交流程

# 创建功能分支
git checkout -b feature/your-feature-name

# 编写代码和测试
# ...

# 运行测试和质量检查
./mvnw clean verify

# 提交代码
git add .
git commit -m "feat: your feature description"

# 推送分支
git push origin feature/your-feature-name

# 创建 Pull Request

项目架构概览

JAiRouter 采用模块化设计,主要包含以下核心模块:

模块包路径职责
authorg.unreal.modelrouter.auth认证授权、JWT、API Key
configorg.unreal.modelrouter.config配置管理、版本控制
routerorg.unreal.modelrouter.router路由、负载均衡、限流、熔断
monitororg.unreal.modelrouter.monitor监控、追踪、指标
persistenceorg.unreal.modelrouter.persistence数据持久化、仓库
commonorg.unreal.modelrouter.common公共工具、异常、常量

详细信息请参考 架构说明


常用命令

构建命令

# 完整构建(包含所有检查)
./mvnw clean package

# 快速构建(跳过检查)
./mvnw clean package -Pfast

# 中国镜像加速
./mvnw clean package -Pchina

测试命令

# 运行所有测试
./mvnw test

# 运行特定测试
./mvnw test -Dtest=LoadBalancerTest

# 生成覆盖率报告
./mvnw clean test jacoco:report

质量检查

# 代码风格检查
./mvnw checkstyle:check

# 静态分析
./mvnw spotbugs:check

# 完整质量检查
./mvnw verify

开发工具集成

代码质量工具

工具用途配置文件
Checkstyle代码风格检查checkstyle.xml
SpotBugs静态代码分析spotbugs-security-*.xml
JaCoCo代码覆盖率分析pom.xml

测试框架

框架用途
JUnit 5主要测试框架
MockitoMock 框架
Spring Boot Test集成测试支持
Reactor Test响应式流测试

扩展开发

添加新适配器

  1. 创建适配器类继承 BaseAdapter
  2. 实现请求转换和响应映射逻辑
  3. 注册到 AdapterRegistry
  4. 编写单元测试

详细说明请参考 贡献指南

添加新负载均衡策略

  1. 实现 LoadBalancer 接口
  2. LoadBalancerFactory 中注册
  3. 添加配置支持
  4. 编写测试用例

添加新限流算法

  1. 实现 RateLimiter 接口
  2. RateLimiterFactory 中注册
  3. 添加 YAML 配置支持
  4. 编写并发测试

获得帮助

如果在开发过程中遇到问题,可以通过以下方式获得帮助:

  • 查看项目文档和 FAQ
  • 搜索已有的 GitHub Issues
  • 创建新的 Issue 描述问题
  • 参与社区讨论

贡献方式

我们欢迎各种形式的贡献:

类型说明
🐛 Bug 报告发现问题请及时报告
功能开发实现新功能或改进现有功能
📚 文档改进完善文档内容和示例
🧪 测试补充增加测试用例提高覆盖率
💡 建议讨论提出改进建议和想法

详细的贡献流程请参考 贡献指南


感谢您对 JAiRouter 项目的贡献!