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

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

• 背景
• 开始使用
• 先决条件
• 如何
  • 克隆
  • 构建
  • 使用
  • 运行
• 另请参阅
  • ResoOS API
  • 启发此项目的 spark
  • 路线图

背景

作为 Spring Boot 和 Spring AI 开发人员，我希望 使用一些库，以便方便地向我的应用程序添加功能， 如下所示

用例：

• 想象一下，您可以使用聊天机器人来搜索餐厅并代表您进行预订，而不是使用 OpenTable 或 Tock。

开始使用

从以下开始：

• 一个 Github 帐户
• （可选）来自 ResOS 的一个 API 密钥
  • 如果您打算注册成为餐馆老板，您只需要一个！
  • 我们将启动一个与 API 兼容的 后端，该后端使用 Spring Boot Starter Data JDBC 实现
• 一个 LLM 提供商
  • 例如，Groq Cloud、OpenRouter 或 OpenAI

先决条件

• Git CLI (2.43.0 或更高版本)
• Github CLI (2.65.0 或更高版本)
• httpie CLI (3.2.2 或更高版本)
• Java SDK (21 或更高版本)
• Maven (3.9.9 或更高版本)
• 一个 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

如何使用

如果您想将任何启动器作为依赖项合并到您自己的项目中，您需要：

添加依赖项

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，请参阅 chatbot 模块的配置。

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

如何运行

您需要首先启动 后端 模块，除非您是餐馆老板，并且您拥有与 ResOS v1.2 API 交互的有效 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"

这里有 chatbot 模块。

但还有一种通过 MCP 客户端配置与 Claude 桌面集成的方法，该配置将使用 MCP 服务器 实现。

使用 Claude Desktop

按照这些说明操作。

将以下节添加到名为 claude_desktop_config.json 的文件中：

"spring-ai-resos": {
  "command": "java",
  "args": [
    "-jar",
    "<path-to-project>/target/spring-ai-resos-mcp-server-0.0.1-SNAPSHOT.jar"
  ]
}

或者用于与后端进行测试

"spring-ai-resos": {
  "command": "java",
  "args": [
    "-Dspring.profiles.active=dev",
    "-jar",
    "<path-to-project>/target/spring-ai-resos-mcp-server-0.0.1-SNAPSHOT.jar"
  ]
}

重新启动 Claude Desktop 实例。 验证您是否有一组新的工具调用可用。 与 Claude 聊天。

使用 Chatbot

按照这些说明操作。

要启动 server 模块，请打开一个终端 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

构建并运行一个与 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

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