home / skills / tencentblueking / bk-ci / utility-components

utility-components skill

safe

This skill helps you leverage utility components to implement JWT authentication, expression parsing, thread pool utilities, and chain of responsibility in

npx playbooks add skill tencentblueking/bk-ci --skill utility-components

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

7.4 KB

---
name: utility-components
description: 工具组件指南，涵盖 JWT 安全认证、表达式解析器、线程池循环工具、责任链模式等特定功能的工具类使用。当用户需要实现 JWT 认证、解析表达式、使用线程池或实现责任链时使用。
core_files:
  - "src/backend/ci/core/common/common-security/src/main/kotlin/com/tencent/devops/common/security/jwt/"
  - "src/backend/ci/core/common/common-expression/"
  - "src/backend/ci/core/common/common-util/src/main/kotlin/com/tencent/devops/common/util/"
related_skills:
  - common-technical-practices
  - design-patterns
token_estimate: 6000
---

# 工具组件指南

## Skill 概述

本 Skill 涵盖了 BK-CI 中常用的 **4 类工具组件**，这些是特定功能的工具类和组件实现。

### 核心主题

| 主题 | 说明 | 文档 |
|------|------|------|
| **JWT 安全认证** | JWT 生成验证、Token 刷新、OAuth2 | [1-jwt-security.md](./reference/1-jwt-security.md) |
| **表达式解析器** | 变量表达式、条件求值、自定义函数 | [2-expression-parser.md](./reference/2-expression-parser.md) |
| **线程池循环工具** | 线程池配置、批量处理、循环工具类 | [3-thread-pool-loop-util.md](./reference/3-thread-pool-loop-util.md) |
| **责任链模式** | 责任链设计、拦截器链、请求处理链 | [4-chain-responsibility.md](./reference/4-chain-responsibility.md) |

---

## ⚠️ 与 `common-technical-practices` 的区别

### 定位对比

| Skill | 定位 | 关注点 | 典型场景 |
|-------|------|--------|----------|
| **common-technical-practices** | **框架级实践** | 如何在 Spring Boot 中使用技术 | AOP 切面、分布式锁、重试机制、参数校验、性能监控、定时任务、审计日志 |
| **utility-components** (本 Skill) | **工具级组件** | 如何使用特定的工具类和组件 | JWT 认证、表达式解析、线程池使用、责任链实现 |

### 使用选择

```
需要实现横切关注点（AOP、锁、重试、监控）
    → 使用 common-technical-practices

需要使用特定工具类（JWT、表达式、线程池、责任链）
    → 使用 utility-components (本 Skill)
```

**示例对比**:
- 需要 **添加性能监控切面** → `common-technical-practices` (reference/5-performance-monitoring.md)
- 需要 **使用线程池批量处理** → `utility-components` (reference/3-thread-pool-loop-util.md)
- 需要 **实现分布式锁** → `common-technical-practices` (reference/2-distributed-lock.md)
- 需要 **实现 JWT 认证** → `utility-components` (reference/1-jwt-security.md)

---

## 工具组件架构

### 组件分层视图

```
┌─────────────────────────────────────────────────────────────┐
│                    BK-CI 业务逻辑层                          │
│      (Process/Project/Store/Auth/Repository...)            │
└─────────────────────────────────────────────────────────────┘
                           ↓
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
   │  JWT    │       │  表达式  │       │  线程池  │
   │  认证   │       │  解析   │       │  工具   │
   └─────────┘       └─────────┘       └─────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ↓
                  ┌────────────────┐
                  │  责任链模式    │
                  │  (拦截器链)    │
                  └────────────────┘
```

---

## 一、JWT 安全认证

详见 [reference/1-jwt-security.md](./reference/1-jwt-security.md)

### 核心功能

- JWT Token 生成与验证
- Token 刷新机制
- 权限校验拦截器
- OAuth2 集成

### 快速开始

```kotlin
// 生成 JWT Token
val token = JwtManager.generateToken(userId, expireTime)

// 验证 Token
val claims = JwtManager.verifyToken(token)
```

---

## 二、表达式解析器

详见 [reference/2-expression-parser.md](./reference/2-expression-parser.md)

### 核心功能

- 变量表达式解析 (`${variable}`)
- 条件表达式求值
- 自定义函数扩展
- 表达式缓存优化

### 快速开始

```kotlin
// 解析变量表达式
val context = mapOf("buildId" to "b-123", "status" to "success")
val result = ExpressionParser.parse("${buildId}_${status}", context)
// 结果: "b-123_success"
```

---

## 三、线程池与循环工具

详见 [reference/3-thread-pool-loop-util.md](./reference/3-thread-pool-loop-util.md)

### 核心功能

- 线程池配置与管理
- 批量任务并发处理
- 循环工具类 (`LoopUtil`)
- 并发控制与优化

### 快速开始

```kotlin
// 批量并发处理
val results = ThreadPoolUtil.executeBatch(taskList) { task ->
    processTask(task)
}

// 循环重试
LoopUtil.loopWithRetry(maxRetries = 3) {
    callExternalApi()
}
```

---

## 四、责任链模式

详见 [reference/4-chain-responsibility.md](./reference/4-chain-responsibility.md)

### 核心功能

- 责任链设计与实现
- 拦截器链模式
- 流水线插件链
- 请求处理链

### 快速开始

```kotlin
// 定义拦截器链
val chain = InterceptorChain()
    .addInterceptor(AuthInterceptor())
    .addInterceptor(ValidationInterceptor())
    .addInterceptor(LoggingInterceptor())

// 执行链
chain.proceed(request)
```

---

## 使用场景决策树

```
用户需求
    ↓
是横切关注点（AOP/锁/重试/监控）？
    ├─ 是 → 使用 common-technical-practices
    └─ 否 → 是否需要特定工具类？
              ├─ JWT 认证 → utility-components (reference/1)
              ├─ 表达式解析 → utility-components (reference/2)
              ├─ 线程池处理 → utility-components (reference/3)
              ├─ 责任链模式 → utility-components (reference/4)
              └─ 其他 → 查找对应模块 Skill
```

---

## 相关 Skill

- [common-technical-practices](../common-technical-practices/SKILL.md) - 通用技术实践（框架级）
- [design-patterns](../design-patterns/SKILL.md) - 设计模式指南
- [backend-microservice-development](../backend-microservice-development/SKILL.md) - 后端微服务开发

---

## Quick Reference

| 需求 | 使用 Skill | 参考章节 |
|------|-----------|----------|
| 实现 JWT 认证 | utility-components | reference/1-jwt-security.md |
| 解析流水线变量 | utility-components | reference/2-expression-parser.md |
| 批量并发处理 | utility-components | reference/3-thread-pool-loop-util.md |
| 实现拦截器链 | utility-components | reference/4-chain-responsibility.md |
| 添加 AOP 切面 | common-technical-practices | reference/1-aop-aspect.md |
| 实现分布式锁 | common-technical-practices | reference/2-distributed-lock.md |
| 配置重试机制 | common-technical-practices | reference/3-retry-mechanism.md |

Overview

This skill provides a compact guide to four utility component families used in CI/CD services: JWT security, expression parsing, thread-pool looping utilities, and the chain-of-responsibility pattern. It focuses on practical usage, code snippets, and decision guidance for applying these tools in Kotlin/Java microservice contexts. The content helps engineers choose the right utility for authentication, dynamic evaluations, concurrent processing, and request interception chains.

How this skill works

The skill explains what each component inspects and does: JWT utilities generate, verify, and refresh tokens and integrate with OAuth2; the expression parser evaluates variable and conditional expressions with custom functions and caching; thread-pool and loop utilities manage concurrent batch tasks, retries, and backoff; the responsibility chain composes interceptors to process requests sequentially. Each section includes quick-start examples and recommended configuration patterns for production safety and performance.

When to use it

Implement stateless authentication, token refresh, or OAuth2 flows for APIs
Evaluate or expand pipeline variables and conditional logic at runtime
Process large batches or concurrent jobs with controlled thread pools and retry loops
Compose request handling, validation, logging, or plugin pipelines using interceptor chains
Choose tool-level solutions when the need is a focused utility rather than a framework-wide cross-cutting concern

Best practices

Keep JWT secrets and signing keys in a secure vault and rotate periodically
Cache parsed expressions and limit dynamic function exposure to avoid injection risks
Tune thread-pool sizes based on CPU, IO characteristics, and observed latency; use bounded queues
Use exponential backoff and max-retry limits for external calls to avoid cascading failures
Design interceptors to be idempotent and fail-fast; keep chain handlers small and single-responsibility

Example use cases

Protect CI API endpoints with JWT tokens and token refresh flows
Evaluate pipeline expressions like ${buildId}_${status} with custom functions for formatting
Run thousands of small tasks concurrently using a configured thread pool and loop utilities for batching
Implement an interceptor chain for auth, validation, and audit logging in request pipelines
Wrap external service calls with LoopUtil.loopWithRetry to add resilient retry behavior

FAQ

When should I prefer a utility component over a framework-level feature?

Use utility components when you need a focused tool (JWT, parser, thread pool, chain) that plugs into your codebase. Use framework-level practices for cross-cutting concerns like AOP, distributed locking, or centralized monitoring.

How do I avoid expression injection risks?

Restrict available functions, validate input variables, use whitelists, and cache parsed templates to reduce parsing overhead and limit attack surface.

How many threads should I configure for batch processing?

Start with a calculation based on cores and IO profile (e.g., cores * 2 for IO-bound), run load tests, and use bounded queues with monitoring to adjust safely.