Spring AI Resos

采用API-first方法开发Spring AI增强餐厅预订系统

这个多模块项目托管了一个客户端代码生成，该代码生成自ResOs API的OpenAPI衍生物，并结合了Spring AI实现。 它还包括一个MCP服务器、与Claude一起使用的MCP客户端配置和一个独立的ReactJS驱动的聊天机器人UI。

• 背景
• 入门
• 先决条件
• 如何

- 克隆 - 构建 - 消耗 - 跑

• 文档

- 建筑 -全面的架构文档 - 规划 -路线图和今后的工作 - 项目来源 -这个项目是如何开始的

• 另请参阅

- ResOS API -外部API参考

背景

作为Spring Boot和Spring AI开发人员，我想 使用库，以便为我的应用程序添加功能 对于以下内容

使用案例：

• 想象一下，你可以不使用OpenTable或Tock，而是与聊天机器人交谈，代表你搜索餐厅并预订。

技术

• 弹簧靴4.0.1
• 春季AI 2.0.0-M1
• 春云2025.1.0
• 春季安全7.0.2
• Java 25
• Maven 3.9.11

入门

从以下内容开始：

• Github 账户
• （可选）A API密钥 来自ResOS

- 如果你想注册成为餐馆老板，你只需要一个！ - 我们将启动一个 后端 与API兼容，使用Spring Boot Starter Data JDBC实现

• LLM提供者

- 例如，Groq Cloud、OpenRouter或OpenAI

先决条件

• Git命令行界面（2.43.0或更高版本）
• Github CLI（2.65.0或更高版本）
• httpie命令行界面（3.2.2或更高版本）
• Java SDK（25或更高版本）
• Maven（3.9.11或更高版本）
• LLM提供商帐户（如果使用公共云或商业托管模型）

如何克隆

使用Git CLI

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

使用Github CLI

gh repo clone pacphi/spring-ai-resos

如何构建

打开终端shell，然后执行：

cd spring-ai-resos
mvn clean install

如何消费

如果你想将任何启动器作为依赖项纳入你自己的项目中，你可以：

添加依赖关系

梅文

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

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 可以添加。

配置将在标签中找到 spring.config.activate.on-profile 部分 application.yml 文件。

如何跑步

你需要启动 后端 模块第一，除非您是餐馆老板，并且您有一个有效的API密钥用于与ResOS v1.2 API交互。

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

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可以使用STDIO传输连接到MCP服务器。这允许Claude直接调用餐厅管理工具。

先决条件

1. 获取MCP服务器的STDIO变体：

- 选项A：从版本下载 -下载中心 spring-ai-resos-mcp-server-stdio-{VERSION}.jar 从 发布 页面。 - 选项B：从源代码构建 -快跑 cd mcp-server && mvn clean package -Pstdio

1. 确保后端正在运行（如果使用本地开发）：

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
• 视窗: %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",
        "
/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",
        "
/mcp-server/target/spring-ai-resos-mcp-server-1.0.0-SNAPSHOT.jar"
      ],
      "env": {
        "RESOS_API_ENDPOINT": "http://localhost:8080/api/v1/resos"
      }
    }
  }
}

替换 `

或 ` 带有JAR文件或项目目录的绝对路径。

可用工具

连接后，Claude Desktop将可以访问这些工具：

验证

1. 更新配置后重新启动Claude Desktop
2. 在Claude界面中查找工具图标（锤子）
3. 您应该看到“spring ai resos”与可用工具一起列出
4. 试着问：“给我看看所有顾客”或“有哪些桌子？”

故障排除

服务器未连接：

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

工具未出现：

• 验证配置JSON语法是否有效
• 检查Claude Desktop日志是否有错误
• 完全重新启动Claude Desktop（不仅仅是聊天）

后端连接错误：

• 确保 RESOS_API_ENDPOINT 环境变量正确
• 验证后端是否可以在配置的URL上访问

聊天机器人

遵循这些说明。

要启动 服务器 模块，打开终端shell并执行

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

接下来，我们将在凭证文件中存储一个API密钥，以允许聊天机器人与LLM服务提供商进行交互。

cd ../mcp-client

利用OpenAI

构建并运行与兼容的聊天机器人版本 开放人工智能。你需要 获取API密钥.

启动应用程序之前：

• 创建一个 config 该文件夹将是 src 文件夹。创建一个名为的文件 creds.yml 在那个文件夹里。将您自己的API密钥添加到该文件中。

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

替换 {REDACTED} 以上是您的OpenAI API密钥

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

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

利用Groq Cloud

构建并运行与兼容的聊天机器人版本 Groq Cloud。你需要 获取API密钥. 请注意，Groq目前不支持文本嵌入。所以，如果你打算和 groq-cloud Spring配置文件已激活，您还需要提供其他凭据

启动应用程序之前：

• 创建一个 config 该文件夹将是 src 文件夹。创建一个名为的文件 creds.yml 在那个文件夹里。将您自己的API密钥添加到该文件中。

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

替换 {REDACTED-1} 和 {REDACTED-2} 以上分别使用Groq Cloud API和OpenAI密钥。

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

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

利用OpenRouter

构建并运行与兼容的聊天机器人版本 OpenRouter。你需要 获取API密钥. 请注意，OpenRouter目前不支持文本嵌入。所以，如果你打算和 openrouter Spring配置文件已激活，您还需要提供其他凭据

启动应用程序之前：

• 创建一个 config 该文件夹将是 src 文件夹。创建一个名为的文件 creds.yml 在那个文件夹里。将您自己的API密钥添加到该文件中。

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

替换 {REDACTED-1} 和 {REDACTED-2} 以上分别使用您的OpenRouter API和OpenAI密钥。

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

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

现在，访问http://localhost:8081在您最喜欢的网络浏览器中。

Spring AI ResOs Chatbot