@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-nacos/references//345/212/237/350/203/275/344/275/277/347/224/250.md

@@ -0,0 +1,134 @@
+# Nacos 功能使用
+
+## 服务注册与发现
+
+服务启动后自动注册到 Nacos，无需额外代码。
+
+### 使用 @LoadBalanced 调用其他服务
+
+```java
+@Configuration
+public class RestTemplateConfig {
+    @Bean
+    @LoadBalanced
+    public RestTemplate restTemplate() {
+        return new RestTemplate();
+    }
+}
+
+@Service
+public class UserService {
+    @Autowired
+    private RestTemplate restTemplate;
+
+    public User getUser(Long id) {
+        // 直接使用服务名，负载均衡自动路由
+        return restTemplate.getForObject("http://user-service/users/" + id, User.class);
+    }
+}
+```
+
+### 服务发现配置
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true          # 临时实例（推荐，容器化场景）
+        group: DEFAULT_GROUP
+        weight: 1.0
+        metadata:
+          version: 1.0.0
+          environment: ${spring.profiles.active}
+```
+
+## 动态配置管理
+
+### 方式一：@Value + @RefreshScope（热更新）
+
+```java
+@RestController
+@RefreshScope  // 必须加此注解才能热更新
+public class ConfigController {
+
+    @Value("${app.feature.enabled:false}")
+    private boolean featureEnabled;
+
+    @GetMapping("/config")
+    public String getConfig() {
+        return "Feature enabled: " + featureEnabled;
+    }
+}
+```
+
+### 方式二：@ConfigurationProperties + @RefreshScope
+
+```java
+@Component
+@ConfigurationProperties(prefix = "app")
+@RefreshScope
+@Data
+public class AppConfig {
+    private String name;
+    private Feature feature;
+
+    @Data
+    public static class Feature {
+        private boolean enabled;
+        private int maxUsers;
+    }
+}
+```
+
+在 Nacos 控制台创建配置：
+- **Data ID**：`my-service.yaml`
+- **Group**：`DEFAULT_GROUP`
+- **内容**：
+```yaml
+app:
+  name: My Service
+  feature:
+    enabled: true
+    maxUsers: 100
+```
+
+### 监听配置变更事件
+
+```java
+@Component
+public class ConfigChangeListener {
+
+    @EventListener
+    public void onRefresh(RefreshScopeRefreshedEvent event) {
+        log.info("配置已刷新");
+    }
+
+    @EventListener
+    public void onEnvironmentChange(EnvironmentChangeEvent event) {
+        log.info("配置变更的 key: {}", event.getKeys());
+    }
+}
+```
+
+## 多环境隔离
+
+推荐使用 **namespace** 隔离环境，**group** 隔离业务：
+
+```yaml
+# 开发环境
+spring:
+  cloud:
+    nacos:
+      namespace: dev-namespace-id
+      discovery:
+        group: DEFAULT_GROUP
+
+# 生产环境
+spring:
+  cloud:
+    nacos:
+      namespace: prod-namespace-id
+```

package/templates/.claude/skills/avatar-boot-starter-nacos/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,96 @@
+# Nacos 快速接入与配置
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-nacos</artifactId>
+</dependency>
+```
+
+## 2. 配置（必须使用 spring.config.import）
+
+> ⚠️ **Spring Cloud Alibaba 2023.x 强制要求**，缺少此配置会导致启动失败。
+
+**application.yaml**（主配置，定义服务名）：
+```yaml
+spring:
+  application:
+    name: my-service
+
+server:
+  port: 8080
+```
+
+**application-dev.yml**（环境配置，声明 Nacos 配置导入）：
+```yaml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      namespace: dev
+      username: ${NACOS_USERNAME:nacos}
+      password: ${NACOS_PASSWORD:nacos}
+      config:
+        enabled: true
+        file-extension: yaml
+        group: DEFAULT_GROUP
+      discovery:
+        enabled: true
+        register-enabled: true
+        ephemeral: true
+```
+
+## 3. spring.config.import 格式说明
+
+```
+optional:nacos:{dataId}?group={group}&refreshEnabled=true
+```
+
+| 部分 | 说明 |
+|:--|:--|
+| `optional:` | 配置不存在时不报错（**推荐加上**） |
+| `nacos:` | 指定配置源类型 |
+| `{dataId}` | 配置文件的 Data ID |
+| `?group=XXX` | 指定配置分组 |
+| `&refreshEnabled=true` | 启用配置自动刷新 |
+
+## 4. 常见错误
+
+```yaml
+# ❌ 错误：缺少 spring.config.import
+spring:
+  cloud:
+    nacos:
+      config:
+        enabled: true  # 仅此配置会启动报错
+
+# ❌ 错误：import 写在 cloud.nacos 下面（应在顶层 spring 下）
+spring:
+  cloud:
+    nacos:
+      config:
+        import: ...  # 错误位置
+
+# ✅ 正确：import 在顶层 spring 下
+spring:
+  config:
+    import:
+      - optional:nacos:my-service.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+```
+
+## 5. 共享配置
+
+```yaml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
+      - optional:nacos:common-redis.yaml?group=SHARED_GROUP&refreshEnabled=true
+```

package/templates/.claude/skills/avatar-boot-starter-nacos/references//346/225/205/351/232/234/346/216/222/346/237/245.md

@@ -0,0 +1,64 @@
+# Nacos 故障排查
+
+## 1. 服务注册失败
+
+**问题**：应用启动后未在 Nacos 控制台看到服务
+
+**排查步骤**：
+1. 检查 `spring.cloud.nacos.server-addr` 是否正确
+2. 检查网络连通性：`telnet nacos-server 8848`
+3. 确认 `spring.cloud.nacos.discovery.register-enabled=true`
+4. 开启 DEBUG 日志：`logging.level.com.alibaba.nacos=DEBUG`
+
+## 2. 配置加载失败
+
+**常见错误信息**：
+- `No spring.config.import property has been defined`
+- `dataId must be specified`
+- `illegal URI`
+
+**排查清单**：
+- ✅ 确认已在 `application-{profile}.yml` 中添加 `spring.config.import`
+- ✅ 确认 `spring.config.import` 在**顶层 `spring:`** 下，不是在 `spring.cloud.nacos:` 下
+- ✅ 确认 dataId 格式正确：`optional:nacos:{dataId}?group={group}&refreshEnabled=true`
+- ✅ 确认 `spring.application.name` 在**主配置文件 application.yaml** 中定义
+- ✅ 确认 Nacos 控制台中该 Data ID 存在（或使用 `optional:` 前缀允许不存在）
+- ✅ 确认 namespace 配置正确
+
+**正确配置示例**：
+```yaml
+# application.yaml
+spring:
+  application:
+    name: my-service  # 必须在主配置中定义
+
+# application-dev.yml
+spring:
+  config:
+    import:
+      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
+  cloud:
+    nacos:
+      server-addr: 127.0.0.1:8848
+      config:
+        enabled: true
+        file-extension: yaml
+```
+
+## 3. 配置不刷新
+
+**问题**：修改 Nacos 配置后应用未更新
+
+**排查步骤**：
+1. 确认 `spring.cloud.nacos.config.refresh-enabled=true`（或 `refreshEnabled=true` 在 import 中）
+2. 确认使用 `@RefreshScope` 的 Bean 没有被其他 Bean 缓存引用
+3. 检查日志是否有 `Refresh keys changed`
+4. 某些配置（如数据库连接池）不支持热更新，需要重启应用
+
+## 4. 服务调用失败（使用服务名调用）
+
+**排查步骤**：
+1. 确认目标服务已注册到 Nacos（在服务列表中可见）
+2. 确认 RestTemplate 有 `@LoadBalanced` 注解
+3. 确认服务名大小写完全一致
+4. 检查目标服务的 namespace 和 group 是否与调用方一致