@danqiusheng/nest-nacos 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/LICENSE +21 -21
- package/README.en.md +59 -0
- package/README.md +78 -457
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/nacos-config.service.d.ts +25 -45
- package/dist/nacos-config.service.d.ts.map +1 -1
- package/dist/nacos-config.service.js +241 -102
- package/dist/nacos-config.service.js.map +1 -1
- package/dist/nacos-naming.service.d.ts +16 -46
- package/dist/nacos-naming.service.d.ts.map +1 -1
- package/dist/nacos-naming.service.js +119 -88
- package/dist/nacos-naming.service.js.map +1 -1
- package/dist/nacos.decorators.d.ts +0 -4
- package/dist/nacos.decorators.d.ts.map +1 -1
- package/dist/nacos.decorators.js +1 -12
- package/dist/nacos.decorators.js.map +1 -1
- package/dist/nacos.health.d.ts +2 -6
- package/dist/nacos.health.d.ts.map +1 -1
- package/dist/nacos.health.js +5 -25
- package/dist/nacos.health.js.map +1 -1
- package/dist/nacos.interfaces.d.ts +68 -55
- package/dist/nacos.interfaces.d.ts.map +1 -1
- package/dist/nacos.module.d.ts +0 -9
- package/dist/nacos.module.d.ts.map +1 -1
- package/dist/nacos.module.js +20 -17
- package/dist/nacos.module.js.map +1 -1
- package/dist/nacos.providers.d.ts +1 -10
- package/dist/nacos.providers.d.ts.map +1 -1
- package/dist/nacos.providers.js +12 -23
- package/dist/nacos.providers.js.map +1 -1
- package/dist/nacos.utils.d.ts +6 -0
- package/dist/nacos.utils.d.ts.map +1 -0
- package/dist/nacos.utils.js +79 -0
- package/dist/nacos.utils.js.map +1 -0
- package/package.json +17 -10
package/README.md
CHANGED
|
@@ -1,509 +1,130 @@
|
|
|
1
|
-
# nest-nacos
|
|
1
|
+
# @danqiusheng/nest-nacos
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
面向 NestJS 10/11 的 Nacos 2.x 配置中心与服务注册发现模块。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 兼容性
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| 组件 | 支持范围 |
|
|
8
|
+
|---|---|
|
|
9
|
+
| NestJS | 10.x、11.x |
|
|
10
|
+
| Node.js | >= 16 |
|
|
11
|
+
| Nacos Node SDK | `nacos` 2.6.x |
|
|
12
|
+
| Nacos Server | 2.x(已对 2.5.3 做真实端到端验证) |
|
|
13
|
+
| Nacos Server 3.x | 不支持 |
|
|
14
|
+
| 传输协议 | Nacos 1.x HTTP OpenAPI;不支持 gRPC |
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
`nacos@2.6.x` 没有实现 Nacos 3.x 所需的 gRPC 协议。插件会明确拒绝
|
|
17
|
+
`transport: 'grpc'`,避免请求返回成功但服务端没有落盘的假成功。
|
|
10
18
|
|
|
11
|
-
|
|
12
|
-
2. [安装](#2-安装)
|
|
13
|
-
3. [快速开始](#3-快速开始)
|
|
14
|
-
4. [同步配置 forRoot](#4-同步配置-forroot)
|
|
15
|
-
5. [异步配置 forRootAsync](#5-异步配置-forrootasync)
|
|
16
|
-
6. [服务发现](#6-服务发现)
|
|
17
|
-
7. [配置中心](#7-配置中心)
|
|
18
|
-
8. [装饰器](#8-装饰器)
|
|
19
|
-
9. [健康检查](#9-健康检查)
|
|
20
|
-
10. [API: NacosNamingService](#10-api-nacosnamingservice)
|
|
21
|
-
11. [API: NacosConfigService](#11-api-nacosconfigservice)
|
|
22
|
-
12. [配置项参考](#12-配置项参考)
|
|
23
|
-
13. [常见问题](#13-常见问题)
|
|
19
|
+
插件运行不需要 Java。只有在本机启动 Nacos Server 时才需要与对应 Nacos 版本兼容的 Java;远程已有 Nacos Server 时,Nest 应用只需要 Node.js。
|
|
24
20
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
## 1. 介绍
|
|
28
|
-
|
|
29
|
-
**nest-nacos** 是一个 NestJS 插件,封装了 `nacos-sdk-nodejs`,为 NestJS 应用提供 **服务发现** 和 **配置中心** 能力。基于 gRPC 传输协议,支持 Nacos 2.x / 3.x 服务端。
|
|
30
|
-
|
|
31
|
-
### 特性
|
|
32
|
-
|
|
33
|
-
| 特性 | 说明 |
|
|
34
|
-
|------|------|
|
|
35
|
-
| 动态模块 | 支持 `forRoot` / `forRootAsync`,可配合 `@nestjs/config` 从环境变量读取配置 |
|
|
36
|
-
| 自动注册 | 模块初始化时自动注册服务实例,销毁时自动注销,无需手动管理生命周期 |
|
|
37
|
-
| 配置热更新 | 订阅配置变更,服务端实时推送,内置本地缓存与 JSON 解析 |
|
|
38
|
-
| gRPC 传输 | 默认使用 gRPC,服务端实时推送,无需 UDP 端口,支持自动重连 |
|
|
39
|
-
| 装饰器注入 | 提供 `@InjectNacosNaming` / `@InjectNacosConfig` 装饰器,简化依赖注入 |
|
|
40
|
-
| 健康检查 | 内置 `NacosHealthIndicator`,可对接 `@nestjs/terminus` 暴露健康端点 |
|
|
41
|
-
|
|
42
|
-
### 兼容性
|
|
43
|
-
|
|
44
|
-
| nest-nacos | nacos-sdk-nodejs | Nacos Server | 传输协议 |
|
|
45
|
-
|---|---|---|---|
|
|
46
|
-
| 1.x | 2.6.x | 3.x / 2.x | gRPC(默认)/ HTTP(仅 2.x) |
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## 2. 安装
|
|
51
|
-
|
|
52
|
-
### 步骤 1:安装 nest-nacos 和 nacos SDK
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
# 使用 npm
|
|
56
|
-
npm install nest-nacos nacos
|
|
57
|
-
|
|
58
|
-
# 使用 yarn
|
|
59
|
-
yarn add nest-nacos nacos
|
|
60
|
-
|
|
61
|
-
# 使用 pnpm
|
|
62
|
-
pnpm add nest-nacos nacos
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
### 步骤 2:确保宿主依赖已安装
|
|
66
|
-
|
|
67
|
-
以下包是 peerDependencies,通常 NestJS 项目中已存在:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
### 步骤 3:(可选)安装配置模块
|
|
74
|
-
|
|
75
|
-
如果需要从 `.env` 文件读取 Nacos 配置,安装 `@nestjs/config`:
|
|
21
|
+
## 安装
|
|
76
22
|
|
|
77
23
|
```bash
|
|
78
|
-
npm install @
|
|
24
|
+
npm install @danqiusheng/nest-nacos nacos
|
|
79
25
|
```
|
|
80
26
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
---
|
|
27
|
+
## 模块配置
|
|
84
28
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
以下是一个最小可用示例,展示如何在 `AppModule` 中同时启用服务发现和配置中心:
|
|
88
|
-
|
|
89
|
-
```typescript
|
|
29
|
+
```ts
|
|
90
30
|
import { Module } from '@nestjs/common';
|
|
91
|
-
import { NacosModule } from 'nest-nacos';
|
|
31
|
+
import { NacosModule } from '@danqiusheng/nest-nacos';
|
|
92
32
|
|
|
93
33
|
@Module({
|
|
94
34
|
imports: [
|
|
95
35
|
NacosModule.forRoot({
|
|
36
|
+
config: {
|
|
37
|
+
serverAddr: '127.0.0.1:8848',
|
|
38
|
+
namespace: 'public',
|
|
39
|
+
username: 'nacos',
|
|
40
|
+
password: 'nacos',
|
|
41
|
+
},
|
|
96
42
|
naming: {
|
|
97
43
|
serverList: '127.0.0.1:8848',
|
|
44
|
+
namespace: 'public',
|
|
98
45
|
username: 'nacos',
|
|
99
46
|
password: 'nacos',
|
|
100
47
|
},
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
48
|
+
instances: [{
|
|
49
|
+
serviceName: 'order-service',
|
|
50
|
+
ip: '192.168.1.20',
|
|
51
|
+
port: 3000,
|
|
52
|
+
weight: 1,
|
|
53
|
+
metadata: { env: 'prod', version: '1.1.0' },
|
|
54
|
+
}],
|
|
55
|
+
subscribeConfigs: [
|
|
56
|
+
{ dataId: 'application.yaml', format: 'yaml' },
|
|
57
|
+
{ dataId: 'database.properties', format: 'properties' },
|
|
106
58
|
],
|
|
59
|
+
configLoading: {
|
|
60
|
+
failureMode: 'fallback',
|
|
61
|
+
cacheDir: '.nacos-cache',
|
|
62
|
+
retry: { attempts: 3, delayMs: 300 },
|
|
63
|
+
},
|
|
107
64
|
}),
|
|
108
65
|
],
|
|
109
66
|
})
|
|
110
67
|
export class AppModule {}
|
|
111
68
|
```
|
|
112
69
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
- 连接 Nacos 服务端
|
|
116
|
-
- 注册 `order-service` 实例(192.168.1.100:3000)
|
|
117
|
-
- 应用关闭时自动注销该实例
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
## 4. 同步配置 forRoot
|
|
122
|
-
|
|
123
|
-
适用于配置固定的场景,直接在代码中写入连接参数:
|
|
124
|
-
|
|
125
|
-
```typescript
|
|
126
|
-
import { NacosModule } from 'nest-nacos';
|
|
127
|
-
|
|
128
|
-
NacosModule.forRoot({
|
|
129
|
-
naming: {
|
|
130
|
-
serverList: '127.0.0.1:8848',
|
|
131
|
-
namespace: 'production',
|
|
132
|
-
username: 'nacos',
|
|
133
|
-
password: 'nacos',
|
|
134
|
-
},
|
|
135
|
-
config: {
|
|
136
|
-
serverAddr: '127.0.0.1:8848',
|
|
137
|
-
namespace: 'production',
|
|
138
|
-
},
|
|
139
|
-
// 启动时自动注册的实例
|
|
140
|
-
instances: [
|
|
141
|
-
{
|
|
142
|
-
serviceName: 'order-service',
|
|
143
|
-
ip: '192.168.1.100',
|
|
144
|
-
port: 3000,
|
|
145
|
-
weight: 1.0,
|
|
146
|
-
metadata: { version: '1.0.0' },
|
|
147
|
-
},
|
|
148
|
-
],
|
|
149
|
-
// 启动时预订阅的配置项
|
|
150
|
-
subscribeConfigs: [
|
|
151
|
-
{ dataId: 'database.yaml', group: 'DEFAULT_GROUP' },
|
|
152
|
-
{ dataId: 'redis.yaml', group: 'DEFAULT_GROUP' },
|
|
153
|
-
],
|
|
154
|
-
})
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
---
|
|
158
|
-
|
|
159
|
-
## 5. 异步配置 forRootAsync
|
|
160
|
-
|
|
161
|
-
适用于生产环境,配合 `@nestjs/config` 从环境变量或配置文件读取参数:
|
|
162
|
-
|
|
163
|
-
```typescript
|
|
164
|
-
import { Module } from '@nestjs/common';
|
|
165
|
-
import { ConfigModule, ConfigService } from '@nestjs/config';
|
|
166
|
-
import { NacosModule } from 'nest-nacos';
|
|
167
|
-
|
|
168
|
-
@Module({
|
|
169
|
-
imports: [
|
|
170
|
-
ConfigModule.forRoot({ isGlobal: true }),
|
|
171
|
-
NacosModule.forRootAsync({
|
|
172
|
-
imports: [ConfigModule],
|
|
173
|
-
inject: [ConfigService],
|
|
174
|
-
useFactory: (config: ConfigService) => ({
|
|
175
|
-
naming: {
|
|
176
|
-
serverList: config.get('NACOS_SERVER_ADDR'),
|
|
177
|
-
namespace: config.get('NACOS_NAMESPACE'),
|
|
178
|
-
username: config.get('NACOS_USERNAME'),
|
|
179
|
-
password: config.get('NACOS_PASSWORD'),
|
|
180
|
-
},
|
|
181
|
-
config: {
|
|
182
|
-
serverAddr: config.get('NACOS_SERVER_ADDR'),
|
|
183
|
-
namespace: config.get('NACOS_NAMESPACE'),
|
|
184
|
-
},
|
|
185
|
-
instances: [
|
|
186
|
-
{
|
|
187
|
-
serviceName: config.get('SERVICE_NAME'),
|
|
188
|
-
ip: config.get('SERVICE_IP'),
|
|
189
|
-
port: config.get<number>('SERVICE_PORT'),
|
|
190
|
-
},
|
|
191
|
-
],
|
|
192
|
-
}),
|
|
193
|
-
}),
|
|
194
|
-
],
|
|
195
|
-
})
|
|
196
|
-
export class AppModule {}
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
对应的 `.env` 文件:
|
|
200
|
-
|
|
201
|
-
```env
|
|
202
|
-
NACOS_SERVER_ADDR=127.0.0.1:8848
|
|
203
|
-
NACOS_NAMESPACE=public
|
|
204
|
-
NACOS_USERNAME=nacos
|
|
205
|
-
NACOS_PASSWORD=nacos
|
|
206
|
-
SERVICE_NAME=order-service
|
|
207
|
-
SERVICE_IP=192.168.1.100
|
|
208
|
-
SERVICE_PORT=3000
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
> **说明**:`forRootAsync` 还支持 `useClass` 和 `useExisting` 两种方式,适合需要从远程配置中心或数据库读取 Nacos 连接参数的场景。
|
|
212
|
-
|
|
213
|
-
---
|
|
70
|
+
`forRootAsync` 支持 `useFactory`、`useExisting` 和 `useClass`。
|
|
214
71
|
|
|
215
|
-
##
|
|
72
|
+
## 配置中心
|
|
216
73
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
import { Injectable, OnModuleInit } from '@nestjs/common';
|
|
221
|
-
import { NacosNamingService, InjectNacosNaming } from 'nest-nacos';
|
|
74
|
+
```ts
|
|
75
|
+
import { Injectable } from '@nestjs/common';
|
|
76
|
+
import { InjectNacosConfig, NacosConfigService } from '@danqiusheng/nest-nacos';
|
|
222
77
|
|
|
223
78
|
@Injectable()
|
|
224
|
-
export class
|
|
225
|
-
@
|
|
226
|
-
private readonly naming: NacosNamingService;
|
|
227
|
-
|
|
228
|
-
async onModuleInit() {
|
|
229
|
-
// 订阅 user-service 实例变更(服务端推送)
|
|
230
|
-
this.naming.subscribe('user-service', (hosts) => {
|
|
231
|
-
console.log(`user-service 实例数: ${hosts.length}`);
|
|
232
|
-
});
|
|
233
|
-
}
|
|
234
|
-
|
|
235
|
-
// 查询健康实例并调用
|
|
236
|
-
async callUserService() {
|
|
237
|
-
const instances = await this.naming.selectInstances('user-service');
|
|
238
|
-
if (instances.length === 0) {
|
|
239
|
-
throw new Error('user-service 无可用实例');
|
|
240
|
-
}
|
|
241
|
-
const target = instances[0];
|
|
242
|
-
return `http://${target.ip}:${target.port}`;
|
|
243
|
-
}
|
|
79
|
+
export class SettingsService {
|
|
80
|
+
constructor(@InjectNacosConfig() private readonly nacos: NacosConfigService) {}
|
|
244
81
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
await this.
|
|
248
|
-
|
|
249
|
-
ip: '10.0.0.5',
|
|
250
|
-
port: 8080,
|
|
251
|
-
ephemeral: true,
|
|
252
|
-
});
|
|
82
|
+
async load() {
|
|
83
|
+
const yaml = await this.nacos.getParsedConfig('application.yaml');
|
|
84
|
+
const merged = await this.nacos.getMergedConfig();
|
|
85
|
+
return { yaml, merged };
|
|
253
86
|
}
|
|
254
|
-
}
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
---
|
|
258
87
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
```typescript
|
|
264
|
-
import { Injectable, OnModuleInit } from '@nestjs/common';
|
|
265
|
-
import { NacosConfigService, InjectNacosConfig } from 'nest-nacos';
|
|
266
|
-
|
|
267
|
-
@Injectable()
|
|
268
|
-
export class DbService implements OnModuleInit {
|
|
269
|
-
@InjectNacosConfig()
|
|
270
|
-
private readonly nacosConfig: NacosConfigService;
|
|
271
|
-
|
|
272
|
-
private dbConfig: any;
|
|
273
|
-
|
|
274
|
-
async onModuleInit() {
|
|
275
|
-
// 1. 读取配置(自动解析 JSON)
|
|
276
|
-
this.dbConfig = await this.nacosConfig.getConfigAsJson('database.yaml');
|
|
277
|
-
|
|
278
|
-
// 2. 订阅配置热更新
|
|
279
|
-
this.nacosConfig.subscribe('database.yaml', 'DEFAULT_GROUP', (content) => {
|
|
280
|
-
this.dbConfig = JSON.parse(content);
|
|
281
|
-
console.log('数据库配置已热更新');
|
|
88
|
+
watch() {
|
|
89
|
+
this.nacos.subscribe('application.yaml', 'DEFAULT_GROUP', (raw, parsed) => {
|
|
90
|
+
// 每次服务端变更只回调一次;parsed 是按 dataId/format 解析后的值。
|
|
282
91
|
});
|
|
283
92
|
}
|
|
284
|
-
|
|
285
|
-
async updateConfig() {
|
|
286
|
-
// 发布新配置
|
|
287
|
-
await this.nacosConfig.publish(
|
|
288
|
-
'database.yaml',
|
|
289
|
-
'DEFAULT_GROUP',
|
|
290
|
-
JSON.stringify({ host: '10.0.0.1', port: 3306 }),
|
|
291
|
-
);
|
|
292
|
-
}
|
|
293
93
|
}
|
|
294
94
|
```
|
|
295
95
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
---
|
|
299
|
-
|
|
300
|
-
## 8. 装饰器
|
|
301
|
-
|
|
302
|
-
nest-nacos 提供四个装饰器简化依赖注入:
|
|
96
|
+
支持 JSON、YAML、Properties、TXT 自动解析,多配置深度合并,热更新内存缓存,本地文件回退,以及 `throw` / `fallback` / `continue` 三种启动失败策略。每个 `dataId + group` 只建立一个底层 SDK 订阅。
|
|
303
97
|
|
|
304
|
-
|
|
305
|
-
|--------|----------|------|
|
|
306
|
-
| `@InjectNacosNaming()` | `NacosNamingService` | 注入封装后的 Naming 服务 |
|
|
307
|
-
| `@InjectNacosConfig()` | `NacosConfigService` | 注入封装后的 Config 服务 |
|
|
308
|
-
| `@InjectNacosNamingClient()` | `NacosNamingClient` | 注入原始 SDK 客户端(高级用法) |
|
|
309
|
-
| `@InjectNacosConfigClient()` | `NacosConfigClient` | 注入原始 SDK 客户端(高级用法) |
|
|
98
|
+
## 服务注册与发现
|
|
310
99
|
|
|
311
|
-
|
|
100
|
+
```ts
|
|
101
|
+
const instance = await naming.selectInstance('payment-service', {
|
|
102
|
+
strategy: 'roundRobin', // random | roundRobin | weighted
|
|
103
|
+
metadata: { env: 'prod' },
|
|
104
|
+
});
|
|
312
105
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
InjectNacosNaming,
|
|
319
|
-
InjectNacosConfig,
|
|
320
|
-
} from 'nest-nacos';
|
|
321
|
-
|
|
322
|
-
@Injectable()
|
|
323
|
-
export class MyService {
|
|
324
|
-
@InjectNacosNaming()
|
|
325
|
-
private readonly naming: NacosNamingService;
|
|
326
|
-
|
|
327
|
-
@InjectNacosConfig()
|
|
328
|
-
private readonly config: NacosConfigService;
|
|
329
|
-
|
|
330
|
-
// 也可以用构造函数注入
|
|
331
|
-
constructor(
|
|
332
|
-
private readonly naming2: NacosNamingService,
|
|
333
|
-
private readonly config2: NacosConfigService,
|
|
334
|
-
) {}
|
|
335
|
-
}
|
|
106
|
+
await naming.updateWeight({
|
|
107
|
+
serviceName: 'order-service',
|
|
108
|
+
ip: '192.168.1.20',
|
|
109
|
+
port: 3000,
|
|
110
|
+
}, 0.5);
|
|
336
111
|
```
|
|
337
112
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
## 9. 健康检查
|
|
341
|
-
|
|
342
|
-
内置 `NacosHealthIndicator` 可对接 `@nestjs/terminus`:
|
|
343
|
-
|
|
344
|
-
```typescript
|
|
345
|
-
import { Controller, Get } from '@nestjs/common';
|
|
346
|
-
import { HealthCheckService } from '@nestjs/terminus';
|
|
347
|
-
import { NacosHealthIndicator } from 'nest-nacos';
|
|
113
|
+
模块销毁时会注销由插件注册的实例,并关闭 Naming/Config 客户端。`getServerStatus()` 和 `NacosHealthIndicator.isHealthy()` 均为异步方法:
|
|
348
114
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
private health: HealthCheckService,
|
|
353
|
-
private nacos: NacosHealthIndicator,
|
|
354
|
-
) {}
|
|
355
|
-
|
|
356
|
-
@Get()
|
|
357
|
-
check() {
|
|
358
|
-
return this.health.check([
|
|
359
|
-
() => this.nacos.isHealthy(),
|
|
360
|
-
]);
|
|
361
|
-
}
|
|
362
|
-
}
|
|
115
|
+
```ts
|
|
116
|
+
const status = await naming.getServerStatus();
|
|
117
|
+
const health = await healthIndicator.isHealthy();
|
|
363
118
|
```
|
|
364
119
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
---
|
|
368
|
-
|
|
369
|
-
## 10. API: NacosNamingService
|
|
370
|
-
|
|
371
|
-
| 方法 | 参数 | 返回值 | 说明 |
|
|
372
|
-
|------|------|--------|------|
|
|
373
|
-
| `register(inst)` | `NacosInstanceOptions` | `Promise<void>` | 注册服务实例 |
|
|
374
|
-
| `deregister(inst)` | `NacosInstanceOptions` | `Promise<void>` | 注销服务实例 |
|
|
375
|
-
| `getAllInstances(serviceName, groupName?, clusters?, subscribe?)` | `string, ...` | `Promise<Host[]>` | 查询所有实例 |
|
|
376
|
-
| `selectInstances(serviceName, groupName?, clusters?, healthy?, subscribe?)` | `string, ...` | `Promise<Host[]>` | 查询健康实例 |
|
|
377
|
-
| `subscribe(info, listener)` | `string \| SubscribeInfo, Function` | `void` | 订阅实例变更推送 |
|
|
378
|
-
| `unSubscribe(info, listener?)` | `string \| SubscribeInfo, Function?` | `void` | 取消订阅 |
|
|
379
|
-
| `getServerStatus()` | 无 | `'UP' \| 'DOWN'` | 获取服务端状态 |
|
|
380
|
-
| `getRawClient()` | 无 | `NacosNamingClient \| null` | 获取原始 SDK 客户端 |
|
|
381
|
-
|
|
382
|
-
### subscribe 参数说明
|
|
383
|
-
|
|
384
|
-
`info` 参数支持两种形式:
|
|
120
|
+
高级用法可使用 `@InjectNacosNamingClient()` 和 `@InjectNacosConfigClient()` 注入原始 SDK 客户端。
|
|
385
121
|
|
|
386
|
-
|
|
387
|
-
// 形式一:字符串(serviceName)
|
|
388
|
-
naming.subscribe('user-service', (hosts) => { ... });
|
|
122
|
+
## 验证
|
|
389
123
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
);
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
---
|
|
398
|
-
|
|
399
|
-
## 11. API: NacosConfigService
|
|
400
|
-
|
|
401
|
-
| 方法 | 参数 | 返回值 | 说明 |
|
|
402
|
-
|------|------|--------|------|
|
|
403
|
-
| `getConfig(dataId, group?)` | `string, string?` | `Promise<string>` | 获取配置内容(带缓存) |
|
|
404
|
-
| `getConfigAsJson<T>(dataId, group?)` | `string, string?` | `Promise<T>` | 获取配置并解析为 JSON |
|
|
405
|
-
| `publish(dataId, group, content)` | `string, string, string` | `Promise<boolean>` | 发布配置 |
|
|
406
|
-
| `remove(dataId, group)` | `string, string` | `Promise<boolean>` | 删除配置 |
|
|
407
|
-
| `subscribe(dataId, group, listener)` | `string, string, Function` | `void` | 订阅配置变更推送 |
|
|
408
|
-
| `unSubscribe(dataId, group, listener?)` | `string, string, Function?` | `void` | 取消订阅 |
|
|
409
|
-
| `getRawClient()` | 无 | `NacosConfigClient \| null` | 获取原始 SDK 客户端 |
|
|
410
|
-
|
|
411
|
-
> **默认 group**:`getConfig()` 和 `getConfigAsJson()` 的 `group` 参数默认值为 `'DEFAULT_GROUP'`,如果配置在默认分组下可省略。
|
|
412
|
-
|
|
413
|
-
---
|
|
414
|
-
|
|
415
|
-
## 12. 配置项参考
|
|
416
|
-
|
|
417
|
-
### NacosModuleOptions
|
|
418
|
-
|
|
419
|
-
| 字段 | 类型 | 必填 | 说明 |
|
|
420
|
-
|------|------|------|------|
|
|
421
|
-
| `naming` | `NacosNamingOptions` | 否 | Naming 服务发现配置,不传则不启用 |
|
|
422
|
-
| `config` | `NacosConfigOptions` | 否 | Config 配置中心配置,不传则不启用 |
|
|
423
|
-
| `instances` | `NacosInstanceOptions[]` | 否 | 启动时自动注册的服务实例列表 |
|
|
424
|
-
| `subscribeConfigs` | `{ dataId, group }[]` | 否 | 启动时预订阅的配置项列表 |
|
|
425
|
-
|
|
426
|
-
### NacosNamingOptions
|
|
427
|
-
|
|
428
|
-
| 字段 | 类型 | 默认值 | 说明 |
|
|
429
|
-
|------|------|--------|------|
|
|
430
|
-
| `serverList` | `string \| string[]` | - | Nacos 服务端地址 |
|
|
431
|
-
| `namespace` | `string` | `'public'` | 命名空间 ID |
|
|
432
|
-
| `transport` | `'grpc' \| 'http'` | `'grpc'` | 传输协议 |
|
|
433
|
-
| `username` | `string` | - | 用户名 |
|
|
434
|
-
| `password` | `string` | - | 密码 |
|
|
435
|
-
| `ssl` | `boolean` | `false` | 是否启用 TLS/SSL |
|
|
436
|
-
| `ak` | `string` | - | 阿里云 RAM AccessKey |
|
|
437
|
-
| `sk` | `string` | - | 阿里云 RAM SecretKey |
|
|
438
|
-
| `appName` | `string` | - | 应用名 |
|
|
439
|
-
|
|
440
|
-
### NacosConfigOptions
|
|
441
|
-
|
|
442
|
-
| 字段 | 类型 | 默认值 | 说明 |
|
|
443
|
-
|------|------|--------|------|
|
|
444
|
-
| `serverAddr` | `string \| string[]` | - | Nacos 服务端地址 |
|
|
445
|
-
| `namespace` | `string` | `'public'` | 命名空间 ID |
|
|
446
|
-
| `transport` | `'grpc' \| 'http'` | `'grpc'` | 传输协议 |
|
|
447
|
-
| `username` | `string` | - | 用户名 |
|
|
448
|
-
| `password` | `string` | - | 密码 |
|
|
449
|
-
| `ssl` | `boolean` | `false` | 是否启用 TLS/SSL |
|
|
450
|
-
| `accessKey` | `string` | - | 阿里云 RAM AccessKey |
|
|
451
|
-
| `secretKey` | `string` | - | 阿里云 RAM SecretKey |
|
|
452
|
-
| `signatureRegionId` | `string` | - | v4 签名区域 ID |
|
|
453
|
-
|
|
454
|
-
### NacosInstanceOptions
|
|
455
|
-
|
|
456
|
-
| 字段 | 类型 | 默认值 | 说明 |
|
|
457
|
-
|------|------|--------|------|
|
|
458
|
-
| `serviceName` | `string` | - | 服务名 |
|
|
459
|
-
| `ip` | `string` | - | 实例 IP |
|
|
460
|
-
| `port` | `number` | - | 实例端口 |
|
|
461
|
-
| `weight` | `number` | `1.0` | 权重 |
|
|
462
|
-
| `ephemeral` | `boolean` | `true` | 是否临时实例 |
|
|
463
|
-
| `clusterName` | `string` | - | 集群名 |
|
|
464
|
-
| `groupName` | `string` | `'DEFAULT_GROUP'` | 分组名 |
|
|
465
|
-
| `metadata` | `Record<string, string>` | - | 元数据 |
|
|
466
|
-
|
|
467
|
-
---
|
|
468
|
-
|
|
469
|
-
## 13. 常见问题
|
|
470
|
-
|
|
471
|
-
### 只启用配置中心,不启用服务发现可以吗?
|
|
472
|
-
|
|
473
|
-
可以。`naming` 和 `config` 都是可选的,只传 `config` 即可:
|
|
474
|
-
|
|
475
|
-
```typescript
|
|
476
|
-
NacosModule.forRoot({
|
|
477
|
-
config: { serverAddr: '127.0.0.1:8848' },
|
|
478
|
-
// 不传 naming,NacosNamingService 注入后客户端为 null
|
|
479
|
-
})
|
|
124
|
+
```bash
|
|
125
|
+
npm ci
|
|
126
|
+
npm run build
|
|
127
|
+
npm test
|
|
480
128
|
```
|
|
481
129
|
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
### 如何选择 gRPC 还是 HTTP 传输?
|
|
485
|
-
|
|
486
|
-
| 传输协议 | Nacos 2.x | Nacos 3.x | 推荐场景 |
|
|
487
|
-
|----------|-----------|-----------|----------|
|
|
488
|
-
| `grpc`(默认) | 支持 | 支持 | 推荐,实时推送,无需 UDP |
|
|
489
|
-
| `http` | 支持 | 不支持 | 仅兼容旧版 Nacos 2.x 时使用 |
|
|
490
|
-
|
|
491
|
-
### Nacos 3.x 连接失败怎么办?
|
|
492
|
-
|
|
493
|
-
Nacos 3.x 已移除 HTTP API 支持,必须使用 gRPC 传输(默认)。确保:
|
|
494
|
-
|
|
495
|
-
- 未设置 `transport: 'http'`
|
|
496
|
-
- Nacos Server 的 gRPC 端口(默认 9848,即 serverPort + 1000)已开放
|
|
497
|
-
- 检查用户名密码是否正确
|
|
498
|
-
|
|
499
|
-
### 配置更新后业务代码没有生效?
|
|
500
|
-
|
|
501
|
-
确保通过 `subscribe()` 订阅了配置变更,并在回调中更新本地变量。`getConfig()` 返回的是缓存值,订阅后缓存会自动更新,但业务代码中引用的变量需要手动更新。
|
|
502
|
-
|
|
503
|
-
### 如何获取原始 SDK 客户端?
|
|
504
|
-
|
|
505
|
-
使用 `getRawClient()` 方法或 `@InjectNacosNamingClient()` / `@InjectNacosConfigClient()` 装饰器获取原始 `NacosNamingClient` / `NacosConfigClient` 实例,调用 SDK 未封装的高级 API。
|
|
506
|
-
|
|
507
|
-
---
|
|
508
|
-
|
|
509
|
-
*nest-nacos v1.0.0 · MIT License · 基于 nacos-sdk-nodejs v2.6.x*
|
|
130
|
+
发布前还应针对真实 Nacos 2.x 执行端到端测试,并从服务端接口反查注册、发布和删除结果。
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -27,4 +27,5 @@ __exportStar(require("./nacos-naming.service"), exports);
|
|
|
27
27
|
__exportStar(require("./nacos-config.service"), exports);
|
|
28
28
|
__exportStar(require("./nacos.decorators"), exports);
|
|
29
29
|
__exportStar(require("./nacos.health"), exports);
|
|
30
|
+
__exportStar(require("./nacos.utils"), exports);
|
|
30
31
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,oDAAkC;AAClC,qDAAmC;AACnC,iDAA+B;AAC/B,oDAAkC;AAClC,yDAAuC;AACvC,yDAAuC;AACvC,qDAAmC;AACnC,iDAA+B"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,oDAAkC;AAClC,qDAAmC;AACnC,iDAA+B;AAC/B,oDAAkC;AAClC,yDAAuC;AACvC,yDAAuC;AACvC,qDAAmC;AACnC,iDAA+B;AAC/B,gDAA8B"}
|