使用说明

采用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

如何消费

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

添加依赖关系

梅文

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

配置将在标签中找到 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直接调用餐厅管理工具。

先决条件

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

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",
        "<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`	获取具体开放时间

验证

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

故障排除

服务器未连接：

验证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在您最喜欢的网络浏览器中。

使用说明

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

背景

技术

入门

先决条件

如何克隆

如何构建

如何消费

添加依赖关系

添加配置

如何跑步

使用克劳德桌面

先决条件

配置

可用工具

验证

故障排除

聊天机器人

利用OpenAI

利用Groq Cloud

利用OpenRouter

相关 MCP

知识图谱记忆服务器

Druid MCP服务器

学术论文搜索工具

RAG文档检索与存储服务器

MCP注解服务器

聊天机器人服务器