@goplus123/core-api 1.0.7 → 1.1.0

package/README.md

@@ -260,6 +260,150 @@ const sdk = initSDK({
 
 对应实现：[`initSDK`](./src/index.ts#L372-L578)
 
+### gRPC：按服务路由 baseUrl（多服务地址扩展）
+
+SDK 在每次 gRPC 调用前，会根据 `service.typeName` 自动选择本次请求的 `baseUrl`（见 [`pickBaseUrl`](./src/client/grpcClient.ts#L157-L183)）。
+
+优先级（从高到低）：
+
+1. `resolveBaseUrl(serviceTypeName)`
+2. `baseUrlByService[serviceTypeName]`
+3. `baseUrlByService[namespace]`（`namespace = serviceTypeName.split('.')[0]`）
+4. `autoBaseUrlByNamespace`（`baseUrl + '/{namespace.toLowerCase()}'`）
+5. `baseUrl`（兜底）
+
+注意：`baseUrlByService` 的 key 是严格区分大小写的
+
+- key 要和 `service.typeName` / `namespace` 完全一致（例如 CMS 的 `namespace` 是 `CMS`，而不是 `cms`）
+- 如果 key 没命中且开启了 `autoBaseUrlByNamespace: true`，会走兜底的自动拼路径（你看到的请求地址通常会变成 `.../cms/...`）
+- value 建议使用“纯 URL 字符串”，不要额外带反引号/空格（例如 `https://fpms-nt.platform88.me/cmsx`）
+
+示例 1：自动按 namespace 拼路径（最省事，要求网关按 `/cms`、`/recommend` 这种路径分 service）
+
+```ts
+import { initSDK } from '@goplus123/core-api'
+
+initSDK({
+  grpc: {
+    baseUrl: 'https://fpms-nt.platform88.me',
+    autoBaseUrlByNamespace: true,
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+} as any)
+```
+
+示例 2：用 `baseUrlByService` 做静态映射（真实路由前缀与 typeName 不一致、或少量服务走不同域名/路径）
+
+```ts
+import { initSDK } from '@goplus123/core-api'
+
+initSDK({
+  grpc: {
+    baseUrl: 'https://fpms-nt.platform88.me',
+    baseUrlByService: {
+      recommend: 'https://fpms-nt.platform88.me/recommendation',
+      CMS: 'https://fpms-nt.platform88.me/cmsx',
+      'CMS.FrontendService': 'https://fpms-nt.platform88.me/cmsx',
+      'player.FrontendPlayerService': 'https://fpms-player.platform88.me/player',
+    },
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+} as any)
+```
+
+示例 3：用 `resolveBaseUrl` 做动态解析（最高优先级；适合灰度/环境/复杂规则）
+
+```ts
+import { initSDK } from '@goplus123/core-api'
+
+initSDK({
+  grpc: {
+    baseUrl: 'https://fpms-nt.platform88.me',
+    resolveBaseUrl: (serviceTypeName) => {
+      const ns = serviceTypeName.split('.')[0]
+      const nsLower = ns.toLowerCase()
+      if (nsLower === 'recommend') return 'https://fpms-nt.platform88.me/recommendation'
+      if (nsLower === 'player') return 'https://fpms-player.platform88.me/player'
+      return `https://fpms-nt.platform88.me/${nsLower}`
+    },
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+} as any)
+```
+
+### gRPC：打印请求/响应数据（logPayload）
+
+如果需要在项目中把 gRPC 请求/响应的数据打印出来，可以在 `grpc` 配置里开启 `logPayload`。
+
+它会把 payload 序列化成字符串并写入你传入的 `logger.debug`（例如 `console.debug`），字段名为 `payload`。
+
+```ts
+import { initSDK } from '@goplus123/core-api'
+
+initSDK({
+  grpc: {
+    baseUrl: 'https://example.com/cms',
+    logPayload: true,
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+  logger: console,
+} as any)
+```
+
+也可以做更细的控制：
+
+```ts
+initSDK({
+  grpc: {
+    baseUrl: 'https://example.com/cms',
+    logPayload: {
+      request: true,
+      response: false,
+      maxLength: 20000,
+    },
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+  logger: console,
+} as any)
+```
+
+注意：请避免在生产环境长期开启，尤其是当 payload 可能包含敏感信息（token/手机号等）时。
+
 ### React Native：配置 gRPC invoker（Invoke）（解决 RN 真机 gRPC-Web 兼容问题）
 
 当后端仅提供 gRPC-Web，而 React Native 环境下 `@connectrpc/connect-web` 的 `fetch`/二进制响应解析存在兼容性问题时，可以通过 `grpc.invoker` 注入一层“可替换的底层调用器”，在不改动上层调用方式（`sdk.xxx` / `requestApi` / spec）前提下，切换为 RN 可用的 gRPC-Web 实现。