@dangao/bun-server 3.3.0 → 3.3.1

package/docs/microservice-config-center.md

@@ -21,6 +21,8 @@ The configuration center provides centralized configuration management capabilit
 - **Configuration Priority**: Config center > Environment variables > Default configuration
 - **Configuration Watching**: Watch for configuration changes and automatically refresh application configuration
 
+> **Namespace**: For the Nacos public namespace (console default), omit `namespaceId`. Do not use the literal `"public"`. See [Nacos Integration - Namespace](./microservice-nacos.md#namespace).
+
 ## Quick Start
 
 ### 1. Register Configuration Center Module
@@ -37,7 +39,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },

package/docs/microservice-nacos.md

@@ -5,6 +5,7 @@ This document introduces how to use Nacos as a configuration center and service
 ## Table of Contents
 
 - [Overview](#overview)
+- [Namespace](#namespace)
 - [Nacos Installation](#nacos-installation)
 - [Configuration Center Integration](#configuration-center-integration)
 - [Service Registry Integration](#service-registry-integration)
@@ -20,6 +21,26 @@ Bun Server Framework provides Nacos 3.X support through the `@dangao/nacos-clien
 - **Service Discovery**: Service instance querying and watching
 - **Open API**: Based on Nacos 3.X Open API implementation
 
+## Namespace
+
+The default namespace shown as **public** in the Nacos console maps to an **empty string** `""` in the Open API, not the literal `"public"`.
+
+`@dangao/nacos-client` **0.1.2+** automatically sends `namespaceId=` (empty value) when `namespaceId` is not configured, for both configuration and service discovery. Versions 0.1.1 and earlier omitted the parameter entirely, causing Nacos 3.x to return `code=20004`.
+
+**Recommended**: omit `namespaceId` in client config for the public namespace:
+
+```typescript
+nacos: {
+  client: {
+    serverList: ['http://localhost:8848'],
+    username: 'nacos',
+    password: 'nacos',
+  },
+},
+```
+
+For a custom namespace, pass the ID from the console (usually a UUID). If you patched `@dangao/nacos-client@0.1.1` with `bun patch`, remove `patchedDependencies` and the patch file after upgrading to 0.1.2+.
+
 ## Nacos Installation
 
 ### Docker Installation (Recommended)
@@ -48,7 +69,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -125,7 +145,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -197,7 +216,6 @@ import {
 
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
 });
 
 // Watch for service instance changes
@@ -226,7 +244,6 @@ ConfigCenterModule.forRoot({
   nacos: {
     client: {
       serverList: ['http://localhost:8848'],
-      namespaceId: 'public',
       username: 'nacos',
       password: 'nacos',
     },
@@ -239,7 +256,6 @@ ServiceRegistryModule.forRoot({
   nacos: {
     client: {
       serverList: ['http://localhost:8848'],
-      namespaceId: 'public',
       username: 'nacos',
       password: 'nacos',
     },
@@ -337,6 +353,17 @@ await app.listen(3000);
 - Check if configuration watch callback is correctly implemented
 - Check logs to confirm if configuration changes are detected
 
+### 6. Public Namespace Returns 20004
+
+**Issue**: `getConfig` or service registration/discovery returns `code=20004` when `namespaceId` is not configured
+
+**Cause**: Nacos 3.x requires `namespaceId=` (empty value) in requests; `@dangao/nacos-client` 0.1.1 and earlier omitted the parameter
+
+**Solutions**:
+- Upgrade `@dangao/nacos-client` to **0.1.2+** (pulled in via framework dependency, or pin explicitly in downstream projects)
+- Remove any `bun patch` workaround
+- Do not set `namespaceId` to the literal `"public"`; public maps to an empty string—omit the config instead
+
 ## Reference Resources
 
 - [Nacos Official Documentation](https://nacos.io/docs/latest/)

package/docs/microservice-service-registry.md

@@ -22,6 +22,8 @@ Service registration and discovery provides core capabilities in microservice ar
 - **Health Check**: Automatically update service health status based on health check results
 - **Instance Watching**: Watch for service instance changes
 
+> **Namespace**: Omit `namespaceId` for the Nacos public namespace. See [Nacos Integration - Namespace](./microservice-nacos.md#namespace).
+
 ## Quick Start
 
 ### 1. Register Service Registry Module
@@ -39,7 +41,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -95,7 +96,6 @@ The simplest way is to use the `@ServiceRegistry` decorator:
     region: 'us-east',
   },
   clusterName: 'default',
-  namespaceId: 'public',
   groupName: 'DEFAULT_GROUP',
 })
 @Controller('/api/users')
@@ -113,7 +113,7 @@ class UserController {
 - `healthy`: Initial health status
 - `metadata`: Service metadata (version, region, etc.)
 - `clusterName`: Cluster name
-- `namespaceId`: Namespace
+- `namespaceId`: Namespace ID; omit for public (empty string). See [Nacos Integration - Namespace](./microservice-nacos.md#namespace)
 - `groupName`: Group name
 
 ### Manual Registration
@@ -182,7 +182,6 @@ import type { ServiceInstance } from '@dangao/bun-server';
 class MyService {
   @ServiceDiscovery('user-service', {
     healthyOnly: true, // Only get healthy instances
-    namespaceId: 'public',
     groupName: 'DEFAULT_GROUP',
   })
   public instances: ServiceInstance[] = [];
@@ -200,7 +199,6 @@ class MyService {
 // Get service instance list
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
   groupName: 'DEFAULT_GROUP',
   clusterName: 'default',
 });
@@ -214,7 +212,6 @@ const unsubscribe = serviceRegistry.watchInstances(
     updateLocalCache(newInstances);
   },
   {
-    namespaceId: 'public',
     groupName: 'DEFAULT_GROUP',
   },
 );

package/docs/microservice.md

@@ -40,7 +40,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -55,7 +54,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -230,7 +228,6 @@ class MyService {
 ```typescript
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
 });
 
 // Watch for service instance changes

package/docs/zh/microservice-config-center.md

@@ -21,6 +21,8 @@
 - **配置优先级**：配置中心配置 > 环境变量 > 默认配置
 - **配置监听**：监听配置变更，自动刷新应用配置
 
+> **命名空间**：使用 Nacos public 命名空间（控制台默认）时，省略 `namespaceId` 即可。请勿设为字面量 `"public"`。详见 [Nacos 集成文档 - 命名空间](./microservice-nacos.md#命名空间)。
+
 ## 快速开始
 
 ### 1. 注册配置中心模块
@@ -37,7 +39,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },

package/docs/zh/microservice-nacos.md

@@ -5,6 +5,7 @@
 ## 目录
 
 - [概述](#概述)
+- [命名空间](#命名空间)
 - [Nacos 安装](#nacos-安装)
 - [配置中心集成](#配置中心集成)
 - [服务注册中心集成](#服务注册中心集成)
@@ -20,6 +21,26 @@ Bun Server Framework 通过 `@dangao/nacos-client` 包提供 Nacos 3.X 支持，
 - **服务发现**：服务实例查询和监听
 - **Open API**：基于 Nacos 3.X Open API 实现
 
+## 命名空间
+
+Nacos 控制台默认命名空间显示为 **public**，但其 Open API 中的 ID 是**空字符串** `""`，不是字面量 `"public"`。
+
+`@dangao/nacos-client` **0.1.2+** 在未配置 `namespaceId` 时会自动在请求中附带 `namespaceId=`（空值），适用于配置读取与服务发现。0.1.1 及更早版本会完全省略该参数，导致 Nacos 3.x 返回 `code=20004`。
+
+**推荐做法**：使用 public 命名空间时，省略客户端配置中的 `namespaceId`：
+
+```typescript
+nacos: {
+  client: {
+    serverList: ['http://localhost:8848'],
+    username: 'nacos',
+    password: 'nacos',
+  },
+},
+```
+
+自定义命名空间时传入控制台中的 ID（通常为 UUID）。若曾对 `@dangao/nacos-client@0.1.1` 使用 `bun patch`，升级至 0.1.2+ 后请移除 `patchedDependencies` 及对应 patch 文件。
+
 ## Nacos 安装
 
 ### Docker 安装（推荐）
@@ -48,7 +69,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -125,7 +145,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -197,7 +216,6 @@ import {
 
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
 });
 
 // 监听服务实例变更
@@ -226,7 +244,6 @@ ConfigCenterModule.forRoot({
   nacos: {
     client: {
       serverList: ['http://localhost:8848'],
-      namespaceId: 'public',
       username: 'nacos',
       password: 'nacos',
     },
@@ -239,7 +256,6 @@ ServiceRegistryModule.forRoot({
   nacos: {
     client: {
       serverList: ['http://localhost:8848'],
-      namespaceId: 'public',
       username: 'nacos',
       password: 'nacos',
     },
@@ -337,6 +353,17 @@ await app.listen(3000);
 - 检查配置监听回调是否正确实现
 - 查看日志确认配置变更是否被检测到
 
+### 6. public 命名空间返回 20004
+
+**问题**：未配置 `namespaceId` 时，`getConfig` / 服务注册或发现返回 `code=20004`
+
+**原因**：Nacos 3.x 要求请求携带 `namespaceId=`（空值）；0.1.1 及更早的 `@dangao/nacos-client` 会完全省略该参数
+
+**解决方案**：
+- 升级 `@dangao/nacos-client` 至 **0.1.2+**（框架依赖会自动带入，也可在下游项目中显式升级）
+- 移除 `bun patch`（如有）
+- 不要将 `namespaceId` 设为字面量 `"public"`；public 对应空字符串，推荐直接省略配置
+
 ## 参考资源
 
 - [Nacos 官方文档](https://nacos.io/docs/latest/)

package/docs/zh/microservice-service-registry.md

@@ -22,6 +22,8 @@
 - **健康检查**：自动根据健康检查状态更新服务健康状态
 - **实例监听**：监听服务实例变更
 
+> **命名空间**：使用 Nacos public 命名空间时省略 `namespaceId`。详见 [Nacos 集成文档 - 命名空间](./microservice-nacos.md#命名空间)。
+
 ## 快速开始
 
 ### 1. 注册服务注册中心模块
@@ -39,7 +41,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -94,7 +95,6 @@ await app.listen(3000);
     region: 'us-east',
   },
   clusterName: 'default',
-  namespaceId: 'public',
   groupName: 'DEFAULT_GROUP',
 })
 @Controller('/api/users')
@@ -112,7 +112,7 @@ class UserController {
 - `healthy`：初始健康状态
 - `metadata`：服务元数据（版本、区域等）
 - `clusterName`：集群名
-- `namespaceId`：命名空间
+- `namespaceId`：命名空间 ID；省略表示 public（空字符串）。详见 [Nacos 集成文档 - 命名空间](./microservice-nacos.md#命名空间)
 - `groupName`：分组名
 
 ### 手动注册
@@ -181,7 +181,6 @@ import type { ServiceInstance } from '@dangao/bun-server';
 class MyService {
   @ServiceDiscovery('user-service', {
     healthyOnly: true, // 只获取健康实例
-    namespaceId: 'public',
     groupName: 'DEFAULT_GROUP',
   })
   public instances: ServiceInstance[] = [];
@@ -199,7 +198,6 @@ class MyService {
 // 获取服务实例列表
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
   groupName: 'DEFAULT_GROUP',
   clusterName: 'default',
 });
@@ -213,7 +211,6 @@ const unsubscribe = serviceRegistry.watchInstances(
     updateLocalCache(newInstances);
   },
   {
-    namespaceId: 'public',
     groupName: 'DEFAULT_GROUP',
   },
 );

package/docs/zh/microservice.md

@@ -40,7 +40,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -55,7 +54,6 @@ app.registerModule(
     nacos: {
       client: {
         serverList: ['http://localhost:8848'],
-        namespaceId: 'public',
         username: 'nacos',
         password: 'nacos',
       },
@@ -230,7 +228,6 @@ class MyService {
 ```typescript
 const instances = await serviceRegistry.getInstances('user-service', {
   healthyOnly: true,
-  namespaceId: 'public',
 });
 
 // 监听服务实例变更

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -79,7 +79,7 @@
   },
   "dependencies": {
     "@dangao/logsmith": "0.2.0",
-    "@dangao/nacos-client": "0.1.1",
+    "@dangao/nacos-client": "0.1.2",
     "json5": "^2.2.3",
     "jsonc-parser": "^3.3.1",
     "marked": "^18.0.0",