使用说明

CodePipeline MCP Java Spring OAuth2

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

📑 目录

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

🚀 快速开始

克隆存储库

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

启动依赖关系
```
docker-compose up -d
```
导入Keycloak领域
- 首选 Keycloak管理控制台
- 登录： admin / admin
- 导入： keycloak/realm-export.json

运行应用程序

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

访问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桌面
- 验证： 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配置文件和依赖项。

🚀 入门指南

地方发展设置

克隆存储库

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

启动基础设施
```
docker-compose up -d
```
这将开始：
- PostgreSQL数据库
- Keycloak OAuth2服务器
- PgAdmin（可选，用于数据库管理）
配置Keycloak
- 访问Keycloak管理控制台：http://localhost:8081/
- 使用登录 admin/admin
- 从导入领域配置 keycloak/realm-export.json

运行应用程序

# 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

访问应用程序
- 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
  - 密码：（留空）
测试用户
- 管理用户
  - 用户名： admin
  - 密码： admin
  - 角色： ROLE_ADMIN, ROLE_USER
- 普通用户
  - 用户名： user
  - 密码： password
  - 角色： ROLE_USER

🧪 测试应用程序

运行测试

运行所有测试
```
./mvnw clean test
```

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

# Make sure Docker is running
docker --version

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

运行特定的测试类
```
./mvnw test -Dtest=MessageRepositoryIT
```

运行特定的测试方法

./mvnw test -Dtest=MessageRepositoryIT#shouldSaveMessage

生成测试覆盖率报告

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

测试配置

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

测试剖面

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

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

./mvnw test -Pitest

生成JaCoCo覆盖率报告

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

📚 API文档

认证

获取访问令牌

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

使用访问令牌

GET /api/messages
Authorization: Bearer <access_token>

可用端点

消息

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 <access_token>

{
  "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部署

构建应用程序

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

使用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部署

创建Kubernetes机密

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

部署应用程序
```
kubectl apply -f k8s/
```

🛡️ 安全

身份验证流程

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

安全标头

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

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

📊 监控

执行器端点

端点	描述
`/actuator/health`	应用程序健康信息
`/actuator/info`	申请信息
`/actuator/metrics`	应用程序指标
`/actuator/prometheus`	普罗米修斯指标

日志记录

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

🤝 贡献

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

📄 许可证

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

🙏 致谢

🏗️ 项目结构

.
├── 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配置
安全标头
输入验证

贡献

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

许可证

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

使用说明

CodePipeline MCP Java Spring OAuth2

📑 目录

🚀 快速开始

🚀 最近的更新

📋 ISPW API实施

概述

API终点

分配管理

任务管理

发布管理

发布集管理

数据模型

身份验证流程

错误处理

速率限制

监控

安全标头

🏗️ 系统架构

高级体系结构

身份验证流程

WebSocket消息流

🚀 特性

核心功能

🛠️ 先决条件

🧪 测试

单元测试

集成测试

测试可靠性和故障排除

🚀 入门指南

地方发展设置

🧪 测试应用程序

运行测试

测试配置

测试剖面

📚 API文档

认证

可用端点

消息

WebSocket端点

请求示例

🔧 配置

环境变量

🚀 部署

Docker部署

Kubernetes部署

🛡️ 安全

身份验证流程

安全标头

📊 监控

执行器端点

日志记录

🤝 贡献

📄 许可证

🙏 致谢

🏗️ 项目结构

关键组件

API文档

测试

生产大楼

码头工人

部署

库贝内特斯

云平台

安全

贡献

许可证

致谢

相关 MCP

OBS控制服务器

加密货币数据服务

任务管理协议服务器

Dynamics 365商业中央模型协议服务器

GDB调试分析工具

Figma设计文件MCP服务