编程导航教程

一、项目介绍

这是一套以 Spring AI 实战 + 企业级架构设计 为核心的项目教程，基于 Spring Boot 3 + Spring AI + Vue 3 开发对标大厂的 企业级 AI 网关平台，带大家掌握 AI 时代后端开发必备的多模型接入、智能路由、限流防护等核心技能，大幅提升求职竞争力！

4 大核心能力

1）统一 API 接口：兼容 OpenAI 格式，一行代码即可调用通义千问、智谱 AI、DeepSeek 等主流大模型，无需关心不同厂商的 API 差异。

2）智能路由策略：支持成本优先、速度优先、轮询等多种路由策略，系统自动选择最优模型进行调用，降低成本 30%+。

3）高可用保障：内置健康检查、智能重试、自动 Fallback 机制，确保 99.9% 可用性，单个模型故障不影响业务。

4）完善监控体系：集成 Prometheus + Grafana，实时监控 QPS、成功率、Token 消耗等关键指标，秒级定位问题。

为什么做这个项目？

1）大厂都在用：几乎所有互联网大厂都有自己的 AI 网关服务，用于统一管理和调度内部的 AI 能力。这是 AI 时代基础设施的标配。

2）找工作好用：随着 AI 发展，企业对掌握 AI 接入、多模型管理、成本优化的后端开发者需求激增。这个项目能让你的简历脱颖而出。

3）技术值得学：此项目不仅需要 Spring AI 框架的深度应用，还需要架构设计能力（适配器模式、策略模式）、性能优化能力（限流、缓存）、可观测性建设（监控、链路追踪）等企业级技能。

二、项目优势

项目收获

本项目紧跟 AI 时代、选题新颖、对标大厂 产品架构、技术丰富。区别于增删改查的烂大街项目，我会带你实战大量企业级技术和真实应用场景，掌握层层递进的系统设计、项目扩展和优化方案，帮你成为 AI 时代企业的香饽饽，给你的简历和求职大幅增加竞争力！

企业级 AI 网关项目，技术丰富，玩透 Spring AI~

业务场景真实，实践大量企业解决方案：

鱼皮给大家讲的是 通用的企业级开发方法、AI 网关架构设计套路和最新的 Spring AI 框架技术，从这个项目中你可以学到：

• 如何基于 Spring AI 构建企业级 AI 应用？
• 如何设计灵活的模型适配器，统一接入多个 AI 提供商？
• 如何实现智能路由策略，自动选择成本最优或速度最快的模型？
• 如何设计健康检查机制，实时监控模型状态并自动故障转移？
• 如何基于 Redisson 实现分布式限流，保护 AI 接口不被滥用？
• 如何实现流式响应（SSE），提升 AI 对话的用户体验？
• 如何设计插件系统，让 AI 具备联网搜索、PDF 解析等扩展能力？
• 如何集成 Stripe 支付，实现完整的计费和充值系统？
• 如何基于 Prometheus + Grafana 构建完善的监控告警体系？
• 如何开发 Java SDK，让其他开发者能快速接入你的服务？
• 如何利用 MyBatis Flex 提升开发效率和查询性能？
• 如何从性能、安全性、稳定性、成本等角度全方位优化系统？

此外，还能学会很多架构设计、技术方案对比的方法，提升排查问题、自主解决 Bug 的能力。鱼皮还给大家提供了大量的项目扩展点，有能力的同学可以进一步拉开和别人的区分度，无限进步！

三、业务流程

核心业务流程

从开发者注册登录 => 申请 API Key => 调用 AI 模型 => 查看消耗统计

▼
mermaid
复制代码
graph TD
    A[开发者注册登录] --> B[申请 API Key]
    B --> C{调用方式}
    C -->|网站在线调用| D[在线对话页面]
    C -->|SDK 调用| E[Java SDK]
    C -->|HTTP API 调用| F[直接调用接口]
    D --> G[选择模型]
    E --> G
    F --> G
    G --> H[智能路由选择最优模型]
    H --> I[调用 AI 模型]
    I --> J[返回响应]
    J --> K[统计 Token 消耗]
    K --> L[查看个人中心数据]

API 调用流程

详细的 API 请求处理链路：

▼
mermaid
复制代码
graph LR
    A[客户端请求] --> B[API Key 认证]
    B --> C[配额检查]
    C --> D{指定模型?}
    D -->|是| E[固定路由]
    D -->|否/auto| F[智能路由]
    F --> G[健康检查]
    G --> H[选择最优模型]
    H --> I[模型适配器]
    E --> I
    I --> J[调用 AI 模型]
    J --> K{调用成功?}
    K -->|是| L[返回响应]
    K -->|否| M[Fallback]
    M --> G
    L --> N[记录日志]
    N --> O[统计 Token]

管理员视角

管理员可以后台管理业务数据和监控系统状态：

▼
mermaid
复制代码
graph TD
    A[管理员登录] --> B[用户管理]
    A --> C[模型管理]
    A --> D[监控大盘]
    B --> B1[查看用户列表]
    B --> B2[禁用/启用用户]
    B --> B3[配额管理]
    C --> C1[模型提供者管理]
    C --> C2[模型配置]
    C --> C3[查看健康状态]
    D --> D1[实时 QPS 监控]
    D --> D2[Token 消耗统计]
    D --> D3[模型调用分布]

解决方案实战

AI 技术实战：

• Spring AI 框架深度应用
• 多模型适配器设计
• 智能路由策略实现
• SSE 流式响应
• 插件系统架构
• AI 绘图接口开发

系统架构设计：

• 适配器模式统一多模型接入
• 策略模式实现灵活路由
• 定时任务实现健康检查
• 多角度系统优化（性能/安全/稳定性/成本等）

经典业务：

• API Key 管理
• 请求日志记录
• Token 消耗统计
• 用户余额管理
• 在线充值支付
• 调用历史查询

安全与权限：

• 用户模块和 AOP 权限校验
• Redisson 分布式限流
• IP 黑名单防护
• API Key 认证

监控与可观测性：

• Prometheus 指标收集
• Grafana 可视化监控
• TraceId 全链路追踪

四、功能模块

用户模块

• 用户注册
• 用户登录
• 用户注销
• 获取当前登录用户信息
• 用户权限控制
• 【管理员】管理用户
• 【管理员】用户配额管理

AI 对话模块

• 在线对话页面
• 模型选择（下拉菜单）
• 流式响应展示（打字机效果）
• Token 消耗实时显示
• 对话历史记录
• 插件调用（Web 搜索、PDF 解析等）

API Key 管理

• 创建 API Key
• 查看 Key 列表
• 撤销/删除 Key
• Key 使用统计
• 调用次数限制

模型管理模块

• 模型提供者管理
• 模型配置管理
• ⭐️ 模型健康检查
• ⭐️ 全局启用/禁用控制
• 优先级设置
• 超时时间配置

智能路由模块

• ⭐️ 成本优先路由
• ⭐️ 速度优先路由
• ⭐️ 轮询策略
• ⭐️ 自动 Fallback
• 健康状态监控

限流与安全

• ⭐️ API Key 级别限流
• ⭐️ IP 级别限流
• ⭐️ IP 黑名单管理
• 请求日志记录
• TraceId 追踪

Java SDK

• ⭐️ 同步调用
• ⭐️ 流式调用
• ⭐️ 重试机制
• ⭐️ 异常处理
• 完整文档和示例

数据统计模块

• Token 消耗统计
• 调用历史查询
• 用户消耗排行
• 模型调用分布
• 费用统计

计费与支付（高级）

• ⭐️ Stripe 支付集成
• 用户余额管理
• 充值记录
• 余额扣减
• 消费账单

AI 绘图（高级）

• 文生图接口
• 图片生成历史
• 图片下载

插件系统（高级）

• ⭐️ 插件注册与管理
• ⭐️ Web 搜索插件
• PDF 解析插件
• 图片识别插件

BYOK（高级）

• ⭐️ 用户自带密钥
• 密钥加密存储
• 直连计费模式

监控大盘

• ⭐️ 实时 QPS 监控
• ⭐️ 成功率/错误率统计
• ⭐️ Token 消耗趋势
• ⭐️ 模型健康状态
• Prometheus 指标导出
• Grafana 可视化

系统优化

• ⭐️ 性能优化
• ⭐️ 安全优化
• ⭐️ 流量保护
• ⭐️ 成本优化
• ⭐️ 稳定性优化

五、技术选型

后端

核心：

• Spring Boot 3.5.9 框架
• Java 21（虚拟线程）
• ⭐️ Spring AI 1.1.2
• ⭐️ MyBatis Flex 数据访问

AI 技术：

• ⭐️ Spring AI 多模型集成
• ⭐️ 模型适配器设计
• ⭐️ 智能路由策略
• ⭐️ SSE 流式响应
• 通义千问 / 智谱 AI / DeepSeek
• ⭐️ AI 绘图模型（通义万相）

数据存储：

• MySQL 8.0+ 数据库
• ⭐️ Redis 7+ 分布式缓存
• MyBatis Flex ORM 框架

企业级能力：

• ⭐️ Redisson 分布式限流
• ⭐️ Resilience4j 熔断器
• ⭐️ Micrometer 指标收集
• ⭐️ Prometheus 监控
• ⭐️ Grafana 可视化

设计模式：

• ⭐️ 实战：适配器模式、策略模式、工厂模式
• 了解：单例模式、建造者模式

支付与安全：

• ⭐️ Stripe 支付 SDK
• 数据加密存储

工具库：

• Hutool 工具库
• Lombok 注解库
• Knife4j + Swagger 接口文档

前端

核心：

• Vue 3.5 + Composition API
• Ant Design Vue 4.2 组件库
• Pinia 3.0 全局状态管理
• Axios 1.11 请求库
• TypeScript 5.8 类型安全

可视化：

• ECharts 5.5 图表展示
• Day.js 日期处理

⭐️ 工程化：

• Vite 7.0 构建工具
• ESLint 代码校验
• Prettier 代码美化
• OpenAPI 代码生成

基础设施

部署工具：

• Docker + Docker Compose
• Nginx Web 服务器
• Prometheus 指标存储
• Grafana 监控可视化

开发工具：

• ⭐️ Cursor 编辑器 AI 辅助开发
• JetBrains IDEA 后端
• JetBrains WebStorm 前端

六、架构设计

从客户端发送请求开始，自上而下经过一系列处理，最终得到 AI 模型的响应结果。架构图如下：

核心设计理念：

1. 统一接口：兼容 OpenAI 格式，降低接入成本
2. 智能路由：自动选择最优模型，平衡成本和性能
3. 高可用：健康检查 + 自动重试 + Fallback，保证服务稳定
4. 可观测：完善的监控指标，实时掌握系统状态

七、准备工作

AI 基础知识

建议先观看《程序员鱼皮 AI 指南》，了解 AI 基础知识和学习路线，后续在项目中实战时会有个大致的印象，便于学习理解。

⭐️ 推荐观看视频版：https://www.bilibili.com/video/BV1i9Z8YhEja

文字版：https://www.codefather.cn/course/1907378983347892226

如果项目经验不多、或者自主学习能力一般，建议学这个项目前，先学习鱼皮的 AI 超级智能体项目，这样学这个项目时会更加轻松。

Spring AI 前置学习

本项目大量使用 Spring AI 框架，建议提前了解：

⭐️ 官方文档：https://docs.spring.io/spring-ai/reference/

⭐️ Spring AI Alibaba 文档：https://java2ai.com/docs/quick-start

当然，即使没有学过 Spring AI，也不影响项目的学习，因为鱼皮会从 0 开始带大家实践。

工具资源

项目教程中会使用 AI 辅助编程，建议至少准备一款 AI 开发工具，首推 Cursor。

当然，即使没有 AI 工具，也不影响项目的学习，因为鱼皮会提供现成的代码。

AI 学习资源

1、AI 面试题

建议大家在学习 AI 项目的过程中，持续阅读 AI 大模型相关的面试题，巩固知识点。我们的程序员面试刷题神器面试鸭搞了个 AI 大模型面试题库，建议没事就阅读一些题目来学习学习。

2、开源 AI 知识库

由于 AI 技术日新月异，建议大家平时多关注 AI 相关的资讯动态，比如 鱼皮开源的 AI 知识库，汇总了热门的 AI 大模型和工具，比如 Deepseek 使用指南、提示词技巧分享、知识干货、应用场景、AI 变现、行业资讯、教程资源等一系列内容，帮助你快速掌握 AI 技术，走在时代前沿。

3、免费 AI 交流

鱼皮 AI 导航网站 为大家提供了免费 AI 教程、AI 资源大全、最新 AI 资讯、AI 学习交流社区，大家可以畅所欲言，共同拥抱 AI。

八、学习大纲

为了帮大家循序渐进地学习，鱼皮将项目设计为三个阶段，可以根据自己的时间和水平按需学习。

第一阶段 - 核心平台开发

第 1 期：项目总览

• 项目介绍
• 项目优势
• 业务流程
• 功能模块
• 技术选型
• 架构设计
• 准备工作（前置知识 + AI 学习资源）
• 学习大纲

第 2 期：项目初始化与用户模块（前后端）

• 后端项目初始化（Spring Boot 3 + Spring AI）
• 前端项目初始化（Vue 3 + Ant Design Vue）
• 数据库设计与建表
• 用户模块开发（注册、登录、权限控制、用户管理）

第 3 期：AI 对话核心（后端）

• Spring AI 框架入门
• 模型适配器设计（策略模式）
• 单模型接入（通义千问）
• /v1/chat/completions 接口（兼容 OpenAI 格式）
• SSE 流式响应实现
• Token 消耗统计

第 4 期：AI 对话核心（前端）

• API Key 管理页面
• 在线对话页面
• 流式响应展示（打字机效果）
• 模型选择组件
• Token 消耗显示

第二阶段 - 企业级功能扩展

第 5 期：多模型与智能路由（后端）

• 多模型提供者接入（智谱 AI、DeepSeek）
• 模型提供者管理
• 模型管理与配置
• 路由策略引擎（成本优先 / 速度优先 / 轮询）
• 模型健康检查（定时任务）
• 自动 Fallback 机制

第 6 期：多模型与智能路由（前端）

• 模型提供者管理页面
• 模型管理页面
• 对话页面优化（模型选择、策略配置）
• 健康状态展示

第 7 期：限流与安全防护

• API Key 级别限流（Redisson + 令牌桶）
• IP 级别限流
• IP 黑名单管理（后端）
• 黑名单管理页面（前端）
• 自定义限流注解 + AOP

第 8 期：Java SDK 开发

• SDK 架构设计
• 核心 API 设计（同步 / 流式调用）
• HTTP 客户端封装
• 异常处理机制
• 重试策略实现
• SDK 使用示例与文档

第 9 期：数据统计与个人中心

• Token 消耗统计优化（后端）
• 调用历史查询
• 用户配额管理
• 个人中心页面（前端）
• 调用历史页面
• 用户管理增强（禁用 / 启用）

第三阶段 - 高级功能与部署

第 10 期：计费与支付系统

• 费用计算引擎（后端）
• 用户余额管理
• 余额扣减逻辑
• Stripe 支付集成（沙盒环境）
• Webhook 回调处理
• 充值中心页面（前端）
• 支付成功 / 取消页面
• 余额显示与管理

第 11 期：多模态 AI 功能

• 多模态 AI 概述（文本、图片、音频、视频）
• 图片生成模型接入（通义万相）
• /v1/images/generations 接口（后端）
• 图片生成历史记录
• AI 绘图页面（前端）
• 其他多模态功能扩展（音频、视频介绍）

第 12 期：插件系统

• 插件系统架构设计（后端）
• 插件注册与管理
• Web 搜索插件实现
• PDF 解析插件实现
• 图片识别插件实现
• 对话页面插件集成（前端）
• 插件管理页面

第 13 期：BYOK（用户自带密钥）

• BYOK 功能设计（后端）
• 用户密钥加密存储
• 密钥验证与使用逻辑
• 直连计费模式
• 我的密钥管理页面（前端）
• 对话页面 BYOK 集成

第 14 期：高级监控与可观测性

• Micrometer 指标集成
• Prometheus 指标导出
• TraceId 全链路追踪
• 日志规范化（Logback）
• Grafana 监控大盘配置
• 告警规则配置

第 15 期：项目部署上线

• Docker Compose 一键部署
• 后端 JAR 包部署
• 前端 Nginx 部署