@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-nacos-config/references/configuration-properties.md

@@ -1,295 +0,0 @@
-# `@ConfigurationProperties` 配置项管理（configuration-properties）
-
-> **目的**：补齐 v2.4.0 复核发现的覆盖缺口——研发版 `meritdata-platform-config-item` 的 `MeritdataCloudProperties` 实体类 + `@ConfigurationProperties` 标准用法。
-> **场景**：业务可配置参数（连接池 / 超时 / 业务开关）+ `@RefreshScope` 热更新。
-> **来源**：研发版 `meritdata-platform-config-item` v1.0.0 + 攻略-11。
-
----
-
-## 一、MeritdataCloudProperties 模式
-
-### 1.1 平台实体类（应用配置根）
-
-平台约定所有二开业务配置**必须挂在 `meritdata.cloud.*` 前缀下**：
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud")
-public class MeritdataCloudProperties {
-
-    /**
-     * 二开业务通用配置子节点
-     */
-    private YourApp yourApp = new YourApp();
-
-    @Data
-    public static class YourApp {
-        private Integer poolSize = 10;        // 连接池大小
-        private Long timeoutMs = 3000L;        // 超时（毫秒）
-        private Boolean enabled = true;        // 业务开关
-        private String bizPrefix = "";         // 业务前缀
-    }
-}
-```
-
-### 1.2 Nacos 配置（Nacos 控制台）
-
-```
-data-id: common-${APP_NAME}.properties
-group: DEFAULT_GROUP
-
-# 内容
-meritdata.cloud.your-app.pool-size=20
-meritdata.cloud.your-app.timeout-ms=5000
-meritdata.cloud.your-app.enabled=true
-meritdata.cloud.your-app.biz-prefix=pur_
-```
-
-### 1.3 启用配置类
-
-```java
-@SpringBootApplication
-@EnableConfigurationProperties(MeritdataCloudProperties.class)
-public class YourApplication { ... }
-```
-
----
-
-## 二、3 步标准用法（MUST）
-
-### Step 1：定义配置类
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
-public class YourAppProperties {
-    private Integer poolSize = 10;
-    private Long timeoutMs = 3000L;
-    private Boolean enabled = true;
-}
-```
-
-### Step 2：Nacos 配置
-
-```properties
-meritdata.cloud.yourapp.pool-size=20
-meritdata.cloud.yourapp.timeout-ms=5000
-meritdata.cloud.yourapp.enabled=true
-```
-
-### Step 3：注入使用（带 `@RefreshScope`）
-
-```java
-@Service
-@RefreshScope  // Nacos 变更自动刷新
-public class YourService {
-    @Autowired private YourAppProperties props;
-
-    public void doIt() {
-        if (props.getEnabled()) {
-            // ...
-        }
-    }
-}
-```
-
----
-
-## 三、与 `@Value` / `@NacosValue` 的区别
-
-| 维度 | `@Value` | `@ConfigurationProperties` | `@NacosValue` |
-|------|----------|----------------------------|---------------|
-| **配置源** | application.yml | application.yml / Nacos | 仅 Nacos |
-| **批量绑定** | ❌ 单个字段 | ✅ POJO 全字段 | ❌ 单个字段 |
-| **类型安全** | ⚠️ SpEL 表达式 | ✅ 强类型 | ⚠️ SpEL |
-| **热更新** | ❌ | ✅（@RefreshScope）| ✅（自动监听）|
-| **校验** | ❌ | ✅（@Validated）| ❌ |
-| **典型场景** | 简单单值 | 业务配置组 | Nacos 专项值 |
-
-**推荐**：
-- 业务配置（连接池/超时/开关）→ `@ConfigurationProperties` + `@RefreshScope`
-- Nacos 简单动态值 → `@NacosValue`
-- application.yml 单值 → `@Value`
-
----
-
-## 四、高级用法
-
-### 4.1 配置校验（`@Validated`）
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
-@Validated
-public class YourAppProperties {
-
-    @Min(value = 1, message = "pool-size 必须 ≥ 1")
-    private Integer poolSize = 10;
-
-    @NotNull
-    @Min(value = 100, message = "timeout-ms 必须 ≥ 100")
-    private Long timeoutMs = 3000L;
-
-    @Pattern(regexp = "^[a-z_]+$", message = "biz-prefix 必须小写蛇形")
-    private String bizPrefix = "";
-}
-```
-
-启动时若校验失败，**应用启动直接报错**（fail-fast）：
-
-```
-***************************
-APPLICATION FAILED TO START
-***************************
-Description:
-Binding to target com.example.YourAppProperties@xxx failed:
-
-    Reason: pool-size 必须 ≥ 1
-    Value: 0
-```
-
-### 4.2 嵌套配置（List / Map）
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
-public class YourAppProperties {
-
-    /** 业务白名单列表 */
-    private List<String> whitelist = new ArrayList<>();
-
-    /** 多数据源映射 */
-    private Map<String, DataSourceConfig> dataSources = new HashMap<>();
-
-    @Data
-    public static class DataSourceConfig {
-        private String url;
-        private String username;
-        private String password;
-    }
-}
-```
-
-```properties
-# Nacos 配置
-meritdata.cloud.yourapp.whitelist[0]=user1
-meritdata.cloud.yourapp.whitelist[1]=user2
-
-meritdata.cloud.yourapp.dataSources.master.url=jdbc:mysql://...
-meritdata.cloud.yourapp.dataSources.master.username=root
-```
-
-### 4.3 监听 Nacos 变更
-
-```java
-@Component
-public class YourAppPropertiesListener {
-
-    @Autowired
-    private YourAppProperties props;
-
-    @NacosConfigListener(dataId = "common-yourapp.properties")
-    public void onConfigChange(String newConfig) {
-        log.info("Nacos 配置变更: {}", newConfig);
-        // 配置变更后的额外逻辑（如清缓存）
-    }
-}
-```
-
----
-
-## 五、典型场景
-
-### 5.1 数据库连接池配置
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.datasource")
-public class DataSourceProperties {
-    private Integer poolSize = 20;
-    private Long connectionTimeoutMs = 30000L;
-    private Long idleTimeoutMs = 600000L;
-}
-```
-
-```properties
-meritdata.cloud.datasource.pool-size=50
-meritdata.cloud.datasource.connection-timeout-ms=10000
-```
-
-### 5.2 业务开关（feature flag）
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.feature")
-public class FeatureProperties {
-    private Boolean enableNewApproval = false;     // 新审批流开关
-    private Boolean enableAsyncExport = true;      // 异步导出开关
-    private String  apiRateLimit = "1000";         // API 限流 QPS
-}
-```
-
-```java
-@Service
-@RefreshScope
-public class ApprovalService {
-    @Autowired private FeatureProperties feature;
-
-    public void submit() {
-        if (feature.getEnableNewApproval()) {
-            // 新审批流
-        } else {
-            // 旧审批流
-        }
-    }
-}
-```
-
-### 5.3 超时配置
-
-```java
-@Data
-@Configuration
-@ConfigurationProperties(prefix = "meritdata.cloud.httpclient")
-public class HttpClientProperties {
-    private Long connectTimeoutMs = 3000L;
-    private Long readTimeoutMs = 10000L;
-    private Integer retryCount = 3;
-}
-```
-
----
-
-## 六、与其他 skill 的协作
-
-| 场景 | 协作 skill |
-|------|----------|
-| NacosUtils 10 方法（动态读写配置）| `meritdata-platform-nacos-config/references/guide.md` |
-| Nacos 灰度发布流程 | `meritdata-nacos-importer/references/gray-publish.md` |
-| 敏感配置加密（数据库密码）| `meritdata-platform-nacos-config/references/encryption.md` |
-| 攻略-11 配置项使用 | `meritdata-platform-nacos-config/references/config-item-攻略/INDEX.md` |
-
----
-
-## 七、常见错误
-
-| 错误 | 后果 | 正确做法 |
-|------|------|---------|
-| 用 `@Value` 单个注入 | 无法统一管理 | `@ConfigurationProperties` |
-| 不加 `@RefreshScope` | Nacos 改了不生效 | 加 `@RefreshScope` |
-| `@RefreshScope` 用 static | 不刷新 | 成员变量 |
-| 配置项 snake_case 跟 camelCase 混 | 反序列化报错 | 统一 camelCase |
-| 不做 `@Validated` | 启动时配置错误不暴露 | 加 `@Validated` + `@Min`/`@NotNull` |
-| 配置变更后不清缓存 | 旧缓存继续生效 | 监听 `onConfigChange` 清缓存 |
-
----
-
-**最后更新**：2026-09-08（v2.4.0 P1 补齐）
-**来源**：研发版 `meritdata-platform-config-item` v1.0.0 + 攻略-11
-**整合位置**：`meritdata-platform-nacos-config/references/configuration-properties.md`

package/skills/meritdata-platform-nacos-config/references/dynamic-refresh.md

@@ -1,156 +0,0 @@
-# Nacos 动态刷新（nacos-config）
-
-> 配置变更后业务代码自动感知，无需重启。
-
----
-
-## 1. 三种刷新粒度
-
-| 粒度 | 实现 | 适用场景 |
-|------|------|---------|
-| **方法级** | `@NacosValue(autoRefreshed = true)` | 单个配置项 |
-| **类级** | `@NacosConfigurationProperties` | 一组相关配置 |
-| **手动** | `NacosConfigService.getConfig()` | 运行时动态查 |
-
-## 2. @NacosValue 自动刷新
-
-```java
-@RestController
-public class FeatureController {
-
-    @NacosValue(value = "${feature.dark-mode:false}", autoRefreshed = true)
-    private boolean darkMode;
-
-    @NacosValue(value = "${feature.max-items:20}", autoRefreshed = true)
-    private int maxItems;
-}
-```
-
-Nacos 配置变更 → 自动推送 → 业务字段更新。
-
-## 3. @NacosConfigurationProperties 推荐方式
-
-```java
-@NacosConfigurationProperties(dataId = "your-2nd-service.yaml", autoRefreshed = true)
-@Data
-public class AppConfig {
-
-    /** 订单超时（秒）*/
-    private int orderTimeout = 30;
-
-    /** 是否启用短信通知 */
-    private boolean smsEnabled = false;
-
-    /** 外部 API 地址 */
-    private String apiUrl;
-
-    /** 允许跨域来源 */
-    private List<String> allowedOrigins;
-}
-```
-
-使用：
-
-```java
-@Service
-public class OrderService {
-
-    @Autowired
-    private AppConfig config;
-
-    public void doSomething() {
-        if (config.isSmsEnabled()) {
-            smsClient.send(...);
-        }
-    }
-}
-```
-
-## 4. 自定义刷新监听
-
-### 4.1 场景
-
-配置变更后需要触发自定义逻辑（如重建缓存）。
-
-### 4.2 实现
-
-```java
-@Component
-public class ConfigRefreshListener implements NacosConfigListener {
-
-    @Override
-    public void onReceived(String dataId, String group, String configInfo) {
-        log.info("配置变更: dataId={}, group={}, info={}", dataId, group, configInfo);
-        // 重建缓存
-        cacheManager.clearAll();
-        // 重新初始化
-        service.init();
-    }
-}
-```
-
-注册监听：
-
-```java
-configService.addListener("your-2nd-service.yaml", "DEFAULT_GROUP", listener);
-```
-
-## 5. ❌ 反模式
-
-### 5.1 ❌ 注解不写 autoRefreshed
-
-```java
-// ❌ 错：配置变更后字段不更新
-@NacosValue(value = "${feature.dark-mode:false}")
-private boolean darkMode;
-
-// ✅ 正确
-@NacosValue(value = "${feature.dark-mode:false}", autoRefreshed = true)
-private boolean darkMode;
-```
-
-### 5.2 ❌ 刷新粒度过细导致性能问题
-
-```java
-// ❌ 错：100 个配置项都加 @NacosValue → 100 个监听器
-@NacosValue(value = "${feature.a}", autoRefreshed = true)
-private String a;
-@NacosValue(value = "${feature.b}", autoRefreshed = true)
-private String b;
-// ... 98 个
-
-// ✅ 正确：相关配置聚合到 @NacosConfigurationProperties
-@NacosConfigurationProperties(dataId = "feature.yaml", autoRefreshed = true)
-public class FeatureConfig {
-    private String a;
-    private String b;
-    // ...
-}
-```
-
-### 5.3 ❌ 刷新失败不处理
-
-```java
-// ❌ 错：自定义刷新逻辑抛出异常 → 配置变更失效
-@Override
-public void onReceived(String dataId, String group, String configInfo) {
-    cacheManager.clearAll();  // 抛出异常
-}
-
-// ✅ 正确：try-catch + 日志
-@Override
-public void onReceived(String dataId, String group, String configInfo) {
-    try {
-        cacheManager.clearAll();
-    } catch (Exception e) {
-        log.error("刷新缓存失败", e);
-    }
-}
-```
-
-## 6. 关联阅读
-
-- [guide.md](guide.md) — Nacos 配置基础
-- [env-and-gray.md](env-and-gray.md) — 多环境隔离
-- [encryption.md](encryption.md) — 敏感配置加密
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-nacos-config/references/encryption.md

@@ -1,182 +0,0 @@
-# Nacos 敏感配置加密（nacos-config）
-
-> 数据库密码、API Key、密钥等敏感配置**禁止明文**存 Nacos。
-
----
-
-## 1. 加密方式
-
-### 1.1 平台支持的方案
-
-| 方案 | 适用 | 配置位置 |
-|------|------|---------|
-| **Nacos 加密插件** | 简单 AES 加密 | Nacos 控制台 |
-| **KMS 集成** | 高安全场景 | 外部 KMS |
-| **Jasypt** | 配置文件加密 | application.yml |
-| **Vault** | 多产品通用 | HashiCorp Vault |
-
-## 2. Nacos 加密插件（推荐）
-
-### 2.1 加密配置项
-
-在 Nacos 控制台编辑配置时，对敏感字段使用加密：
-
-```yaml
-# 原始（明文）
-spring:
-  datasource:
-    password: mySecretPassword123
-
-# 加密后（Nacos 自动用 ENC() 包裹）
-spring:
-  datasource:
-    password: ENC(AES 加密后的密文)
-```
-
-### 2.2 客户端解密
-
-```xml
-<dependency>
-    <groupId>com.alibaba.nacos</groupId>
-    <artifactId>nacos-spring-boot-starter</artifactId>
-</dependency>
-```
-
-平台默认启用解密，业务代码**无感知**。
-
-## 3. KMS 集成（高安全）
-
-### 3.1 场景
-
-金融、医疗场景需要 FIPS-140 级别合规，使用外部 KMS。
-
-### 3.2 配置
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      config:
-        # 配置项值引用 KMS
-        extension-configs[0]:
-          data-id: kms-ref.yaml
-          refresh: true
-```
-
-```yaml
-# kms-ref.yaml（Nacos 配置）
-spring:
-  datasource:
-    password: KMS_REF(database-prod-password)  # 平台启动时从 KMS 取值
-```
-
-### 3.3 业务代码无感知
-
-```java
-@NacosValue(value = "${spring.datasource.password}")
-private String dbPassword;  // 启动时已被 KMS 解析为明文
-```
-
-## 4. Jasypt（配置文件加密）
-
-### 4.1 引入依赖
-
-```xml
-<dependency>
-    <groupId>com.github.ulisesbocchio</groupId>
-    <artifactId>jasypt-spring-boot-starter</artifactId>
-    <version>3.0.5</version>
-</dependency>
-```
-
-### 4.2 配置加密
-
-```bash
-# 用 jasypt 加密密码
-java -cp jasypt-1.9.3.jar \
-  org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
-  algorithm=PBEWithMD5AndDES \
-  input=mySecretPassword123 \
-  password=MY_MASTER_PASSWORD
-
-# 输出：ENC(xxxxxx)
-```
-
-### 4.3 在 Nacos 中使用
-
-```yaml
-spring:
-  datasource:
-    password: ENC(xxxxxx)  # 启动时自动解密
-```
-
-### 4.4 主密码传递
-
-```yaml
-# ❌ 错：主密码写在配置里
-jasypt:
-  encryptor:
-    password: MY_MASTER_PASSWORD
-
-# ✅ 正确：主密码通过环境变量
-jasypt:
-  encryptor:
-    password: ${JASYPT_MASTER_PASSWORD}
-```
-
-启动：
-
-```bash
-JASYPT_MASTER_PASSWORD=xxx java -jar app.jar
-```
-
-## 5. ❌ 反模式
-
-### 5.1 ❌ 明文密码存 Nacos
-
-```yaml
-# ❌ 错：明文密码
-spring:
-  datasource:
-    password: mySecretPassword123
-```
-
-✅ 加密后存储。
-
-### 5.2 ❌ 密钥和加密数据放一起
-
-```yaml
-# ❌ 错：加密的密码 + 解密密钥都在 Nacos
-jasypt:
-  encryptor:
-    password: MY_MASTER_PASSWORD  # 密钥不能和数据放一起
-spring:
-  datasource:
-    password: ENC(xxxxxx)
-```
-
-✅ 主密码从 KMS 或环境变量。
-
-### 5.3 ❌ 加密但不解密
-
-```java
-// ❌ 错：业务代码用了加密字符串
-String password = config.getPassword();  // "ENC(xxxxxx)"
-dataSource.setPassword(password);  // JDBC 连不上
-```
-
-✅ 确保平台已配置解密。
-
-## 6. 审计与合规
-
-- [ ] 所有敏感配置已加密（Nacos 扫描）
-- [ ] 主密钥从外部 KMS 读取
-- [ ] 密钥定期轮换（建议 90 天）
-- [ ] 解密操作有审计日志
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — Nacos 配置基础
-- [dynamic-refresh.md](dynamic-refresh.md) — 动态刷新
-- [env-and-gray.md](env-and-gray.md) — 多环境隔离
-- [SKILL.md](../SKILL.md)