企业官网建设流程全解析

• 示例工程

导读

本指南以payara-micro-example模块为主线，讲解如何基于 Payara Starter 生成的项目骨架，在 Payara Micro 微服务容器中打包、启动一个集成 LangChain4j 的 Jakarta EE 10 / MicroProfile 应用。读完本文，你将掌握 Payara Micro 的运行原理、payara-micro:dev开发模式的完整命令与参数含义、项目依赖与插件配置的作用，以及如何通过自带的前端聊天界面和 Swagger UI 验证应用是否正常运行。

项目概览：Payara Starter 生成的 LangChain4j 示例

payara-micro-example是一个由 Payara Starter 生成的示例应用，归属于 langchain4j-examples 仓库。它展示了典型的 Payara Micro 项目形态：

• 打包方式：WAR 包（<packaging>war</packaging>），由 Payara Micro 运行时直接加载；
• 技术栈：Jakarta EE 10（jakarta.platform:jakarta.jakartaee-api:10.0.0）+ MicroProfile + Payara API，编译目标为 Java 21；
• AI 能力：通过dev.langchain4j:langchain4j、langchain4j-open-ai与langchain4j-google-ai-gemini三个核心依赖（版本1.17.0）接入 LLM；
• 前端界面：自带一个"AI Chat Interface"页面（index.html），支持 OpenAI、Gemini、DeepSeek 三种模型提供商切换；
• API 文档：集成 Swagger UI，提供/openapi的 OpenAPI 端点浏览页面。

模块的源码结构如下：

payara-micro-example/ ├── mvnw / mvnw.cmd # Maven Wrapper ├── pom.xml # 构建与插件配置 ├── README.md # 官方快速开始文档 └── src/ ├── main/ │ ├── java/dev/langchain4j/example/filter/CORSFilter.java │ └── webapp/ │ ├── WEB-INF/{beans.xml, web.xml} │ ├── images/payara-fish-logo.svg │ ├── index.html │ └── swagger.html └── test/ # 预留测试目录

环境准备（Prerequisites）

根据官方 README，本地运行前需要准备：

需要说明的是，当前仓库在payara-micro-example目录下提供了 Maven Wrapper（mvnw与mvnw.cmd），因此即便本机没有全局安装 Maven，也可以直接使用./mvnw完成同样的构建与启动流程，命令效果与 README 中的./mvn一致。

启动应用：核心命令payara-micro:dev详解

官方 README 给出的启动步骤非常简洁，核心就一条命令：

./mvn clean package payara-micro:dev

这条命令由两部分组成，理解其含义对排查问题很有帮助：

1. clean package：先清理target/目录，再执行完整的编译、打包流程，最终产出 WAR 文件。在 pom.xml 中可以看到配套的构建插件：

   • maven-compiler-plugin:3.13.0：按maven.compiler.release=21编译源码；
   • maven-war-plugin:3.4.0：生成 WAR 包，并设置failOnMissingWebXml=false，即允许在没有传统web.xml描述符的情况下打包（现代 Jakarta EE 应用普遍如此，本项目的web.xml仅声明了欢迎页面）。

2. payara-micro:dev：调用fish.payara.maven.plugins:payara-micro-maven-plugin:2.4的dev目标，启动 Payara Micro 开发模式。该插件的关键配置（来自 pom.xml 的payara-micro-maven-plugin配置块）如下：

启动成功后，浏览器访问http://localhost:8080/即可打开应用首页。

启动后的验证入口：AI 聊天界面与 Swagger UI

1. AI Chat Interface（首页）

首页 index.html 是一个纯前端实现的聊天界面：

• 提供OpenAI / Gemini / DeepSeek三个模型提供商的下拉选项；
• 发送消息时，前端会向http://localhost:8080/api/{provider}/chat发起带message查询参数的 GET 请求（例如http://localhost:8080/api/openai/chat?message=hello）；
• 响应以纯文本返回，前端会将 Markdown 风格的代码块、标题、列表渲染为富文本样式。

这表明该 WAR 应用中应当存在JAX-RS端点（/api/openai/chat、/api/gemini/chat、/api/deepseek/chat），分别代理到 langchain4j 的 OpenAI 与 Gemini 模型。虽然当前模块的src/main/java下仅包含 CORS 过滤器源码，但结合 pom.xml 中同时引入langchain4j-open-ai与langchain4j-google-ai-gemini两个模型提供方依赖，可以推断出该界面对应的后端服务是按此结构设计的。

2. Swagger UI 接口文档

项目还集成了 Swagger UI。构建时由download-maven-plugin在generate-resources阶段从 Swagger 官方仓库下载swagger-ui发行包，再由maven-resources-plugin在process-resources阶段将其复制进 WAR 包，因此应用内自带完整的 Swagger 前端资源。

页面 swagger.html 将文档源指向http://localhost:8080/openapi，启动后访问该页面即可在浏览器中浏览、调试应用暴露的所有 REST 端点。

3. 跨域支持

src/main/java/dev/langchain4j/example/filter/CORSFilter.java 是一个标注了@Provider的 JAX-RS 响应过滤器，为所有接口响应添加：

Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Max-Age: -1 Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

它的存在保证前端页面与后端 REST 服务在跨源访问时不会被浏览器拦截，是前后端分离调试（例如本地直接打开index.html）得以顺利进行的关键一环。

深入解读：pom.xml 的关键依赖与运行机制

依赖三件套：Jakarta EE、MicroProfile 与 Payara

pom.xml 通过dependencyManagement引入fish.payara.api:payara-bom与org.jboss.arquillian:arquillian-bom，统一管理版本。核心运行时依赖分三类：

• LangChain4j 系列（1.17.0）：langchain4j（核心库）、langchain4j-open-ai（OpenAI 模型适配）、langchain4j-google-ai-gemini（Gemini 模型适配）；
• Jakarta / MicroProfile API（provided作用域）：jakarta.platform:jakarta.jakartaee-api、org.eclipse.microprofile:microprofile、fish.payara.api:payara-api。这些 API 由 Payara Micro 运行时在部署时提供，因此编译期标记为provided；
• 测试依赖：JUnit 4.13.2、Arquillian JUnit 容器 1.10.0.Final 与 Jersey 客户端/HK2，用于集成测试；maven-surefire-plugin:3.2.5还通过系统属性payara.microJar将测试指向target/payara-micro-${payara.version}.jar。

测试 Profile：payara-micro-managed

pom 中定义了一个默认激活（activeByDefault=true）的payara-micro-managedprofile，用于测试场景：

• 引入fish.payara.arquillian:arquillian-payara-micro-managed作为测试容器；
• 在process-test-classes阶段通过maven-dependency-plugin将指定版本的 Payara Micro 运行时下载并复制到target/payara-micro-${payara.version}.jar，供 Arquillian 管理启动。

这意味着当项目补充集成测试后，执行mvn test会自动下载 Payara Micro 运行时并启动服务实例进行验证。

仓库与版本管理

pom 额外配置了 Payara 官方 Nexus 制品仓库（https://nexus.dev.payara.fish/repository/payara-artifacts），仅启用 release 版本，用于拉取 Payara 相关构件；Payara 版本通过payara.version属性（当前为6.2025.5）统一控制，便于升级。

常见问题与排障建议

小结

payara-micro-example展示了从 Payara Starter 骨架到可运行的 AI 聊天应用的完整链路：WAR 打包 + Payara Micro 运行时 +payara-micro:dev开发模式，配合 LangChain4j 的多模型依赖、内置 Swagger 与 CORS 支持，构成了一个轻量、可快速上手的 Jakarta EE 微服务 AI 应用模板。无论是学习 Payara Micro 的运行机制，还是作为 LangChain4j 在 Java 微服务容器中落地的起点，这个模块都提供了清晰、可复现的实践路径。

• 示例工程