Developing a Spring AI Enhanced Restaurant Booking System Employing an API-first Approach

采用 API 优先方法开发 Spring AI 增强型餐厅预订系统

这个多模块项目包含一个基于 ResOs API 的 OpenAPI 衍生规范生成的客户端代码，以及 Spring AI 实现。 项目还包含 MCP 服务、用于与 Claude 配合使用的 MCP 客户端配置，以及一个独立的 ReactJS 聊天机器人 UI。

• 背景
• 入门
• 先决条件
• 如何操作
  • 克隆
  • 构建
  • 使用
  • 运行
• 文档
  • 架构 - 全面的架构文档
  • 规划 - 路线图和后续工作
  • 项目起源 - 本项目的起源
• 另请参阅
  • ResOS API - 外部 API 参考

背景

作为 Spring Boot 和 Spring AI 开发者，我希望 使用一些库，以便轻松地为我的应用添加功能， 例如以下用例：

• 想象一下，如果你可以与聊天机器人对话，让它代你搜索餐厅并预订座位，而不是使用 OpenTable 或 Tock。

技术

• Spring Boot 4.0.1
• Spring AI 2.0.0-M1
• Spring Cloud 2025.1.0
• Spring Security 7.0.2
• Java 25
• Maven 3.9.11

入门

首先准备：

• 一个 Github 账户
• （可选）一个 ResOS API 密钥
  • 只有打算注册为餐厅经营者时才需要
  • 我们将启动一个与 API 兼容的后端，该后端使用 Spring Boot Starter Data JDBC 实现
• 一个大模型提供商
  • 例如 Groq Cloud、OpenRouter 或 OpenAI

先决条件

• Git CLI（2.43.0 或更高版本）
• Github CLI（2.65.0 或更高版本）
• httpie CLI（3.2.2 或更高版本）
• Java SDK（25 或更高版本）
• Maven（3.9.11 或更高版本）
• 一个大模型提供商账户（如果使用公有云或商业托管模型）

如何克隆

使用 Git CLI

git clone https://github.com/pacphi/spring-ai-resos

使用 Github CLI

gh repo clone pacphi/spring-ai-resos

如何构建

打开终端，然后执行：

cd spring-ai-resos
mvn clean install

如何使用

如果你想在自己的项目中将任何 starter 作为依赖引入，可以按以下步骤操作：

添加依赖

Maven

<dependency>
    <groupId>me.pacphi</groupId>
    <artifactId>spring-ai-resos-client</artifactId>
    <version>{release-version}</version>
</dependency>

Gradle

implementation 'me.pacphi:spring-ai-resos-client:{release-version}'

将上方所有 {release-version} 替换为有效的构件发布版本号

添加配置

遵循 Spring Boot 约定，在以下文件中添加类似这样的配置段：

application.properties

default.url=${RESOS_API_ENDPOINT:https://api.resos.com/v1}

application.yml

default:
  url: ${RESOS_API_ENDPOINT:https://api.resos.com/v1}

要启用客户端，请指定 API 密钥（如有需要），并调整其他相关配置。

请参阅聊天机器人模块的配置，了解可添加的其他 dependencies 和 configuration。

配置位于 application.yml 文件中标记为 spring.config.activate.on-profile 的部分。

如何运行

除非你是餐厅经营者并且拥有与 ResOS v1.2 API 交互所需的有效 API 密钥，否则需要先启动后端模块。

要启动后端，请打开终端并执行：

cd backend
mvn clean spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="--add-opens java.base/java.net=ALL-UNNAMED"

此外，还有聊天机器人模块。

你也可以通过 MCP 客户端配置与 Claude 桌面应用集成，该配置将使用 MCP 服务实现。

使用 Claude Desktop

Claude Desktop 可以通过 STDIO 传输方式连接 MCP 服务。这使 Claude 能够直接调用餐厅管理工具。

前置条件

1. 获取 STDIO 版本的 MCP 服务：
   • 选项 A：从 Releases 下载 - 从 Releases 页面下载 spring-ai-resos-mcp-server-stdio-{VERSION}.jar。
   • 选项 B：从源代码构建 - 运行 cd mcp-server && mvn clean package -Pstdio
2. 确保后端正在运行（如果使用本地开发环境）：

cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="--add-opens java.base/java.net=ALL-UNNAMED"

配置

将以下内容添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

如果使用下载的发行版 JAR：

{
  "mcpServers": {
    "spring-ai-resos": {
      "command": "java",
      "args": [
        "-Dspring.profiles.active=stdio",
        "-jar",
        "<path-to-jar>/spring-ai-resos-mcp-server-stdio-{VERSION}.jar"
      ],
      "env": {
        "RESOS_API_ENDPOINT": "http://localhost:8080/api/v1/resos"
      }
    }
  }
}

如果从源代码构建：

{
  "mcpServers": {
    "spring-ai-resos": {
      "command": "java",
      "args": [
        "-Dspring.profiles.active=stdio",
        "-jar",
        "<path-to-project>/mcp-server/target/spring-ai-resos-mcp-server-1.0.0-SNAPSHOT.jar"
      ],
      "env": {
        "RESOS_API_ENDPOINT": "http://localhost:8080/api/v1/resos"
      }
    }
  }
}

将 <path-to-jar> 或 <path-to-project> 替换为 JAR 文件或项目目录的绝对路径。

可用工具

连接后，Claude Desktop 将能够使用以下工具：

工具	描述
getTables	获取所有餐厅桌位
getCustomers	获取客户记录，支持筛选和分页
getCustomerById	获取指定客户
getFeedback	获取客户反馈和评价
getFeedbackById	获取指定反馈
getOpeningHours	获取未来两周的营业时间
getOpeningHoursById	获取指定营业时间

验证

1. 更新配置后，重启 Claude Desktop
2. 在 Claude 界面中查找工具图标（锤子）
3. 你应该能看到列有可用工具的 “spring-ai-resos”
4. 尝试提问：“显示所有客户”或“有哪些可用桌位？”

故障排除

服务无法连接：

• 确认 JAR 路径是正确的绝对路径
• 确保已安装 Java 25+，且位于 PATH 中
• 检查后端服务是否正在端口 8080 上运行

未显示工具：

• 确认配置 JSON 语法有效
• 检查 Claude Desktop 日志中的错误
• 完全重启 Claude Desktop（而不只是重启聊天）

后端连接错误：

• 确保 RESOS_API_ENDPOINT 环境变量正确
• 确认可通过配置的 URL 访问后端

使用 Chatbot

按照以下说明操作。

要启动 server 模块，请打开终端并执行

cd mcp-server
export RESOS_API_ENDPOINT=http://localhost:8080/api/v1/resos
mvn spring-boot:run -Dspring-boot.run.profiles=cloud,dev

接下来，我们将在凭据文件中保存一个 API 密钥，以便 chatbot 与大模型服务提供商交互。

cd ../mcp-client

使用 OpenAI

构建并运行兼容 OpenAI 的 chatbot 版本。你需要获取 API 密钥。

启动应用前：

• 创建一个与 src 文件夹同级的 config 文件夹。在该文件夹中创建名为 creds.yml 的文件，并在其中添加你自己的 API 密钥。

spring:
  ai:
    openai:
      api-key: { REDACTED }

将上方的 {REDACTED} 替换为你的 OpenAI API 密钥

接下来，要启动 chatbot，请打开终端并执行

mvn spring-boot:run -Dspring-boot.run.profiles=openai,dev

使用 Groq Cloud

构建并运行兼容 Groq Cloud 的聊天机器人版本。你需要获取 API 密钥。 请注意，Groq 目前不支持文本嵌入。因此，如果你打算在启用 groq-cloud Spring 配置文件的情况下运行，还需要提供其他凭据。

启动应用前：

• 创建一个与 src 文件夹同级的 config 文件夹。在该文件夹中创建名为 creds.yml 的文件，并在其中添加你自己的 API 密钥。

spring:
  ai:
    openai:
      api-key: { REDACTED-1 }
      embedding:
        api-key: { REDACTED-2 }

将上方的 {REDACTED-1} 和 {REDACTED-2} 分别替换为你的 Groq Cloud API 密钥和 OpenAI 密钥。

接下来，要启动聊天机器人，请打开终端并执行

mvn spring-boot:run -Dspring-boot.run.profiles=groq-cloud,dev

使用 OpenRouter

构建并运行兼容 OpenRouter 的聊天机器人版本。你需要获取 API 密钥。 请注意，OpenRouter 目前不支持文本嵌入。因此，如果你打算在启用 openrouter Spring 配置文件的情况下运行，还需要提供其他凭据。

启动应用前：

• 创建一个与 src 文件夹同级的 config 文件夹。在该文件夹中创建名为 creds.yml 的文件，并在其中添加你自己的 API 密钥。

spring:
  ai:
    openai:
      api-key: { REDACTED-1 }
      embedding:
        api-key: { REDACTED-2 }

将上方的 {REDACTED-1} 和 {REDACTED-2} 分别替换为你的 OpenRouter API 密钥和 OpenAI 密钥。

接下来，要启动聊天机器人，请打开终端并执行

mvn spring-boot:run -Dspring-boot.run.profiles=openrouter,dev

现在，在你常用的 Web 浏览器中访问 http://localhost:8081。