Codepipeline MCP Javaspring Oauth2

CodePipeline MCP Java Spring OAuth2

一个专业的Java Spring Boot微服务，具有OAuth2身份验证和WebSocket功能，遵循MCP（模型上下文协议）设计原则。

📑 目录

• 快速开始
• 特性
• 系统架构
• API文档
• 配置
• 测试
• 部署
• 安全
• 贡献
• 许可证
• 致谢

🚀 快速开始

1. 克隆存储库

   git clone https://github.com/markbsigler/CodePipeline-MCP-JavaSpring-OAuth2.git
   cd CodePipeline-MCP-JavaSpring-OAuth2

1. 启动依赖关系

   docker-compose up -d

1. 导入Keycloak领域

- 首选 Keycloak管理控制台 - 登录： admin / admin - 导入： keycloak/realm-export.json

1. 运行应用程序

   ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

1. 访问API

- Swagger用户界面 - API基本URL

______________________________________________________________________

🚀 最近的更新

• 测试可靠性和事务环境

- 所有集成测试现在都在事务上下文中运行，确保可靠的回滚和隔离。 - 通过使用注释测试类和设置方法，修复了存储库集成测试中的TransactionRequiredException错误 @Transactional. - 改进了使用测试容器和PostgreSQL运行和排除集成测试故障的文档。

• 增强型短信服务

- 添加了消息创建的输入验证（内容和发件人的空/空检查） - 改进了验证失败的错误消息 - 修复了消息删除中的并发问题 - 为所有服务方法增加了全面的测试覆盖范围 - 提高了测试可靠性和隔离性 - 在测试用例中添加了适当的清理 - 修复了更新操作中的版本处理问题

• 基础设施和测试

- 已升级到 测试容器1.19.7 更好的Java 17兼容性 - 添加 PostgreSQL测试容器 可靠数据库测试的集成 - 实施全面 消息存储库 与真实数据库的集成测试 - 添加 BasePostgres复发试验 用于一致的测试设置 - 改进了测试隔离 @DataJpa测试 以及适当的交易管理 - 添加 PostgresTestConfig 用于容器配置 - 为所有CRUD操作实施了全面的测试用例 - 为自定义存储库方法增加了测试覆盖率 - 通过适当的容器生命周期管理提高了测试可靠性

📋 ISPW API实施

概述

此服务实现ISPW API规范，为管理分配、任务、发布和发布集提供端点。该实现遵循RESTful原则，包括全面的错误处理、验证和安全性。

API终点

分配管理

graph TD
    A[GET /api/assignments] --> B[List Assignments]
    B --> C[Filter by status/application]
    D[POST /api/assignments] --> E[Create Assignment]
    E --> F[Validate input]
    G[GET /api/assignments/id] --> H[Get Assignment Details]
    H --> I[Include tasks]
    J[PUT /api/assignments/id] --> K[Update Assignment]
    K --> L[Validate ownership]
    M[DELETE /api/assignments/id] --> N[Delete Assignment]
    N --> O[Cascade delete tasks]

任务管理

graph TD
    A[GET /api/assignments/id/tasks] --> B[List Tasks]
    B --> C[Filter by status]
    D[POST /api/assignments/id/tasks] --> E[Create Task]
    E --> F[Validate assignment exists]
    G[PUT /api/tasks/id] --> H[Update Task]
    H --> I[Check permissions]
    J[DELETE /api/tasks/id] --> K[Delete Task]
    K --> L[Update assignment status]

发布管理

graph TD
    A[GET /api/releases] --> B[List Releases]
    B --> C[Filter by application/status]
    D[POST /api/releases] --> E[Create Release]
    E --> F[Validate input]
    G[GET /api/releases/id] --> H[Get Release Details]
    H --> I[Include release sets]
    J[PUT /api/releases/id] --> K[Update Release]
    K --> L[Validate ownership]
    M[DELETE /api/releases/id] --> N[Delete Release]
    N --> O[Cascade delete sets]

发布集管理

graph TD
    A[POST /api/releases/id/sets] --> B[Create Release Set]
    B --> C[Validate release exists]
    D[GET /api/releases/id/sets/setId] --> E[Get Set Details]
    E --> F[Include deployment history]
    G[PUT /api/releases/id/sets/setId] --> H[Update Set]
    H --> I[Validate status transition]
    J[POST /api/releases/id/sets/setId/deploy] --> K[Deploy Set]
    K --> L[Trigger deployment workflow]

数据模型

erDiagram
    ASSIGNMENT ||--o{ TASK : has
    ASSIGNMENT {
        String id PK
        String title
        String description
        String status
        String owner
        LocalDateTime dueDate
    }
    
    TASK {
        String id PK
        String title
        String description
        String status
        String assignee
        LocalDateTime dueDate
        String assignmentId FK
    }
    
    RELEASE ||--o{ RELEASE_SET : contains
    RELEASE {
        String id PK
        String name
        String application
        String status
        String owner
        LocalDateTime targetDate
    }
    
    RELEASE_SET {
        String id PK
        String name
        String status
        String owner
        String description
        String releaseId FK
        LocalDateTime deployedAt
        String deployedBy
    }

身份验证流程

sequenceDiagram
    participant C as Client
    participant A as Application
    participant K as Keycloak
    
    C->>K: 1. Request Access Token (Client Credentials/Password)
    K-->>C: 2. JWT Token
    C->>A: 3. API Request with JWT
    A->>K: 4. Validate Token
    K-->>A: 5. Token Info (Roles/Permissions)
    A-->>C: 6. Response
    
    Note over C,A: All endpoints require valid JWT token
    Note over C,A: Admin role required for write operations

错误处理

API以以下格式返回适当的HTTP状态代码和错误消息：

{
    "timestamp": "2025-06-05T19:45:30.123456Z",
    "status": 404,
    "error": "Not Found",
    "message": "Release not found with id: 123",
    "path": "/api/releases/123"
}

常见的错误响应包括：

• 400 Bad Request：输入数据无效
• 401 Unauthorized：身份验证缺失或无效
• 403 Forbidden：权限不足
• 404 Not Found：未找到资源
• 409 Conflict：资源冲突（例如，重复名称）
• 500 Internal Server Error：服务器端错误

速率限制

所有端点都受到速率限制的保护：

• 每个经过身份验证的用户每分钟100个请求
• 公共端点每IP每分钟1000个请求

监控

所有端点都进行了监测：

• 请求/响应指标
• 错误率
• 响应时间
• 活动连接

安全标头

所有响应都包含安全标头：

• Content-Security-Policy
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Strict-Transport-Security: max-age=31536000 ; includeSubDomains

🏗️ 系统架构

高级体系结构

graph TD
    A[Client] -->|HTTPS| B[API Gateway / Load Balancer]
    B --> C[Spring Boot Application]
    C --> D[PostgreSQL]
    C --> E[Keycloak]
    C --> F[Redis Cache]
    
    G[WebSocket Client] -->|WSS| C
    C -->|WebSocket Events| G
    
    H[Monitoring] -->|Metrics| C
    C -->|Logs| I[ELK Stack]

身份验证流程

sequenceDiagram
    participant C as Client
    participant A as Application
    participant K as Keycloak
    
    C->>K: 1. Request Access Token (Client Credentials/Password)
    K-->>C: 2. JWT Token
    C->>A: 3. API Request with JWT
    A->>K: 4. Validate Token
    K-->>A: 5. Token Info
    A-->>C: 6. Response

WebSocket消息流

sequenceDiagram
    participant C as WebSocket Client
    participant S as Spring App
    participant B as Message Broker
    
    C->>S: 1. Connect (STOMP)
    S-->>C: 2. CONNECTED
    C->>S: 3. SUBSCRIBE /topic/messages
    C->>S: 4. SEND /app/chat
    S->>B: 5. Process Message
    B-->>S: 6. Broadcast
    S-->>C: 7. MESSAGE (to all subscribers)

🚀 特性

核心功能

• 弹簧靴3.2 Java 17

- 现代Java功能和性能改进 - 自动配置和独立部署

• 安全

- OAuth2资源服务器 通过JWT验证 - 钥匙斗篷 身份管理集成 - 基于角色的访问控制 （RBAC） - CSRF保护 - 跨域资源共享 配置

• 实时通信

- 双向通信 支持STOMP协议 - 消息广播 以及直接消息传递 - 用户在场 追踪 - 事件驱动 建筑

• 数据层

- PostgreSQL 随着 Spring数据JPA - 迁飞路线 用于数据库迁移 - QueryDSL 用于类型安全查询 - 审计 （createdAt、updatedAt等）

• API

- 表现层状态转移 端点 - OpenAPI 3.0 文档与 Swagger用户界面 - 哈托阿斯 用于可发现的API - 分页 和 过滤 - 验证 和 错误处理

• 开发运维

- 码头工人 和 Docker Compose 支持 - 梅文 构建系统 - Git 版本控制 - CI/CD 准备

• 监控

- 弹簧靴执行器 - 健康检查 - 指标 普罗米修斯 - 分布式跟踪

• 测试

- JUnit5 用于单元和集成测试 - 测试容器 用于与真实数据库的集成测试 - PostgreSQL测试容器 用于可靠的数据库测试 - @DataJpa测试 用于存储库层测试 - MockMVC 用于控制器测试 - 测试覆盖率 JaCoCo的报告 - 测试剖面 适用于不同的环境 - 容器再利用 为了更快地执行测试

🛠️ 先决条件

• Java开发工具包（JDK）17 或以后

- 下载Eclipse Temurin JDK 17 - 验证： java -version - Java 17语言功能和模块所必需的

• Maven 3.9+ 或 Gradle 8+

- 安装Maven - 验证： mvn -v

• Docker和Docker Compose

- - 验证： docker --version 和 docker-compose --version

• 数据库

- PostgreSQL 14+（包含在Docker Compose中） - 或安装 PostgreSQL 本地

• 集成开发环境 （推荐）

- 智能J IDEA - VS代码 带有Java扩展 - 日蚀

• API测试工具

- 邮递员 - 卷曲 - httpie

🧪 测试

单元测试

运行所有单元测试：

./mvnw test

集成测试

集成测试需要Docker（用于测试容器）。如果Docker不可用，这些测试将自动跳过。

运行集成测试：

./mvnw verify -Pintegration-test

• 集成测试使用带有真实PostgreSQL实例的测试容器，以实现完全的可靠性和类似生产的行为。
• 所有存储库和服务集成测试都用以下注释 @Transactional 以确保自动回滚和隔离。
• 每次测试后，使用以下方法隔离和回滚测试数据 @Transactional.
• 通过参数化测试和Docker可用性检查提高了测试可靠性。

测试可靠性和故障排除

• 事务上下文： 所有集成测试都带有注释 @Transactional 在类或方法级别。如果你看到 TransactionRequiredException，确保您的测试类或设置方法已用注释 @Transactional.
• 测试容器： 集成测试需要Docker运行。如果Docker不可用，将跳过测试。在执行集成测试之前，请确保Docker正在运行。
• 数据库清理： 使用以下命令在测试之间自动清理测试数据 deleteAllInBatch() 以及交易回滚。
• 运行特定测试：

- 仅运行存储库集成测试：

    ./mvnw test -Dtest=MessageRepositoryIT

- 运行特定的测试方法：

    ./mvnw test -Dtest=MessageRepositoryIT#shouldSaveMessageSuccessfully

• 常见问题：

- TransactionRequiredException：添加 @Transactional 你的测试课程或方法。 - Connection refused 或 Could not connect to PostgreSQL：确保Docker和PostgreSQL容器正在运行。 - Testcontainers not found：确保您使用了正确的Maven配置文件和依赖项。

🚀 入门指南

地方发展设置

1. 克隆存储库

   git clone https://github.com/markbsigler/CodePipeline-MCP-JavaSpring-OAuth2.git
   cd CodePipeline-MCP-JavaSpring-OAuth2

或者使用SSH：

   git clone git@github.com:markbsigler/CodePipeline-MCP-JavaSpring-OAuth2.git
   cd CodePipeline-MCP-JavaSpring-OAuth2

1. 启动基础设施

   docker-compose up -d

这将开始：

- PostgreSQL数据库 - Keycloak OAuth2服务器 - PgAdmin（可选，用于数据库管理）

1. 配置Keycloak

- 访问Keycloak管理控制台：http://localhost:8081/ - 使用登录 admin/admin - 从导入领域配置 keycloak/realm-export.json

1. 运行应用程序

   # Using Maven wrapper
   ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

   # Or build and run the JAR
   ./mvnw clean package
   java -jar target/codepipeline-mcp-0.0.1-SNAPSHOT.jar

1. 访问应用程序

- API基本URL: http://localhost:8080/api - Swagger用户界面: http://localhost:8080/api/swagger-ui.html - H2控制台: http://localhost:8080/api/h2-控制台 - JDBC网址： jdbc:h2:mem:testdb - 用户名： sa - 密码：（留空）

1. 测试用户

- 管理用户 - 用户名： admin - 密码： admin - 角色： ROLE_ADMIN, ROLE_USER - 普通用户 - 用户名： user - 密码： password - 角色： ROLE_USER

🧪 测试应用程序

运行测试

1. 运行所有测试

   ./mvnw clean test

1. 使用测试容器运行集成测试

   # Make sure Docker is running
   docker --version

   # Run integration tests
   ./mvnw test -Dtest=*IT

1. 运行特定的测试类

   ./mvnw test -Dtest=MessageRepositoryIT

1. 运行特定的测试方法

   ./mvnw test -Dtest=MessageRepositoryIT#shouldSaveMessage

1. 生成测试覆盖率报告

   ./mvnw clean verify
   # Report will be available at: target/site/jacoco/index.html

测试配置

• 测试使用 测试容器 随着 PostgreSQL 14
• 测试数据在测试之间自动清理
• 数据库架构由管理 休眠 在测试配置文件中
• 测试使用 JUnit5 和 断言J 用于断言

测试剖面

• test：单元测试的默认配置文件（内存H2数据库中）
• itest：集成测试配置文件（PostgreSQL测试容器）

要使用特定配置文件运行：

./mvnw test -Pitest

1. 生成JaCoCo覆盖率报告

   ./mvnw jacoco:report
   # Open target/site/jacoco/index.html in browser

📚 API文档

认证

1. 获取访问令牌

   POST /auth/realms/mcp/protocol/openid-connect/token
   Content-Type: application/x-www-form-urlencoded

   client_id=mcp-client
   &username=user
   &password=password
   &grant_type=password
   &client_secret=your-client-secret

1. 使用访问令牌

   GET /api/messages
   Authorization: Bearer 

可用端点

消息

• GET /api/messages -获取所有邮件（分页）
• GET /api/messages/{id} -按ID获取消息
• POST /api/messages -创建新消息
• PUT /api/messages/{id} -更新消息
• DELETE /api/messages/{id} -删除消息
• GET /api/messages/search?query={query} -搜索邮件

WebSocket端点

• /ws -WebSocket端点
• /topic/messages -订阅消息更新
• /queue/private -私人消息队列
• /app/chat -发送消息

请求示例

创建消息

POST /api/messages
Content-Type: application/json
Authorization: Bearer 

{
  "content": "Hello, World!",
  "recipient": "user2"
}

订阅消息

const socket = new SockJS('/ws');
const stompClient = Stomp.over(socket);

stompClient.connect({}, function(frame) {
    console.log('Connected: ' + frame);
    
    // Subscribe to public messages
    stompClient.subscribe('/topic/messages', function(message) {
        console.log('New message: ' + message.body);
    });
    
    // Subscribe to private messages
    stompClient.subscribe('/user/queue/private', function(message) {
        console.log('Private message: ' + message.body);
    });
});

🔧 配置

环境变量

创建一个 .env 项目根目录中的文件，包含以下变量：

# Application
SERVER_PORT=8080
SERVER_SERVLET_CONTEXT_PATH=/api

# Database
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/mcp_db
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres

# JPA/Hibernate
SPRING_JPA_HIBERNATE_DDL_AUTO=update
SPRING_JPA_SHOW_SQL=true

# OAuth2 Resource Server
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=http://localhost:8081/realms/mcp
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI=http://localhost:8081/realms/mcp/protocol/openid-connect/certs

# Logging
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=INFO
LOGGING_LEVEL_COM_CODEPIPELINE=DEBUG

# Actuator
MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,info,metrics
MANAGEMENT_ENDPOINT_HEALTH_SHOW_DETAILS=always

🚀 部署

Docker部署

1. 构建应用程序

   ./mvnw clean package -DskipTests
   docker build -t codepipeline-mcp .

1. 使用Docker Compose运行

   # For development
   docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

   # For production
   docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Kubernetes部署

1. 创建Kubernetes机密

   kubectl create secret generic db-secret \
     --from-literal=username=postgres \
     --from-literal=password=postgres

1. 部署应用程序

   kubectl apply -f k8s/

🛡️ 安全

身份验证流程

1. 客户端向Keycloak请求访问令牌
2. Keycloak发出JWT令牌
3. 客户端将令牌包含在 Authorization 头球
4. 资源服务器验证令牌并检查作用域/角色

安全标头

默认情况下，该应用程序包含以下安全标头：

• 内容安全策略（CSP）
• X-内容-类型选项
• X-Frame-Options
• X-XSS-Protection
• 严格的运输安全（HSTS）

📊 监控

执行器端点

日志记录

日志被写入 logs/application.log 并且可以配置为 logback-spring.xml.

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• Spring Boot
• Spring Security
• 钥匙斗篷
• 码头工人
• 库贝内特斯
• PostgreSQL
• 双向通信

🏗️ 项目结构

.
├── src/
│   ├── main/
│   │   ├── java/com/codepipeline/mcp/
│   │   │   ├── config/          # Configuration classes
│   │   │   ├── controller/      # REST controllers
│   │   │   ├── dto/            # Data Transfer Objects
│   │   │   ├── exception/      # Exception handling
│   │   │   ├── model/          # JPA entities
│   │   │   ├── repository/     # Spring Data repositories
│   │   │   ├── security/       # Security configurations
│   │   │   ├── service/        # Business logic
│   │   │   └── websocket/      # WebSocket configurations
│   │   └── resources/
│   │       ├── application.yml       # Main configuration
│   │       ├── application-dev.yml   # Development profile
│   │       └── application-prod.yml  # Production profile
│   └── test/                    # Test classes
├── .github/                    # GitHub workflow files
├── docker/                     # Docker configuration files
├── k8s/                        # Kubernetes manifests
├── keycloak/                   # Keycloak configuration
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── mvnw
├── pom.xml
└── README.md

关键组件

• config/：Spring配置类

- SecurityConfig.java：安全配置 - WebSocketConfig.java：WebSocket配置 - OpenAPIConfig.java：OpenAPI/Swagger配置

• controller/：REST控制器

- MessageController.java：消息REST端点 - WebSocketController.java：WebSocket消息处理

• model/：JPA实体

- Message.java：带有JPA注释的消息实体

• service/：业务逻辑

- MessageService.java：消息业务逻辑

• security/：安全配置

- JwtRoleConverter.java：JWT角色转换 - SecurityUtils.java：安保设施

• websocket/：WebSocket组件

- WebSocketEventListener.java：WebSocket事件处理 - WebSocketMessageBrokerConfig.java：WebSocket代理配置

API文档

API文档可在运行时使用Swagger UI获得：

• Swagger用户界面：http://localhost:8080/api/swagger-ui.html
• OpenAPI JSON：http://localhost:8080/api/v3/api-docs

测试

运行单元测试：

./mvnw test

运行集成测试（需要Docker）：

./mvnw verify -Pintegration-test

生产大楼

构建应用程序：

./mvnw clean package -DskipTests

码头工人

构建Docker镜像：

docker build -t codepipeline-mcp .

使用Docker Compose运行：

docker-compose up -d

部署

库贝内特斯

部署到Kubernetes：

kubectl apply -f k8s/

云平台

该应用程序可以部署到任何支持Docker容器的云平台：

• AWS ECS/EKS
• 谷歌云运行/GKE
• Azure容器应用/AKS
• Heroku

安全

• 带有JWT令牌的OAuth2
• 基于角色的访问控制（RBAC）
• CSRF保护
• CORS配置
• 安全标头
• 输入验证

贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• Spring Boot
• Spring Security
• 钥匙斗篷
• 码头工人
• 库贝内特斯