@goplus123/core-api 1.0.6 → 1.0.8

package/README.md

@@ -260,11 +260,19 @@ const sdk = initSDK({
 
 对应实现：[`initSDK`](./src/index.ts#L372-L578)
 
-### React Native：注入 gRPC invoker（解决 RN 真机解析 gRPC-Web 响应问题）
+### 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 实现。
 
 这个 `invoker` 只是一个“可插拔的 unary 调用实现”，不限定必须使用某个第三方库。
+内置的 `builtin` invoker 使用的是 gRPC-Web（二进制）协议：`application/grpc-web+proto`。
+
+`grpc.invoker` 支持两种形态（优先级从高到低）：
+
+- `invoker: GrpcInvoker`：使用外部传入的自定义 invoker
+- `invoker: 'builtin'`：使用 SDK 内置的 gRPC-Web unary invoker（基于 `fetch` + `toBinary/fromBinary`）
+
+注意：使用 `invoker: 'builtin'` 时，请确保 `grpc.protocol` 为 `'grpc-web'`。
 
 `invoker.unary()` 的入参约定：
 
@@ -275,7 +283,37 @@ const sdk = initSDK({
 - `headers`：最终要发出去的 headers（已合并 auth/getHeaders/静态 headers 与 callOptions.headers）
 - `callOptions`：透传的调用选项（例如 timeout），按你的底层实现自行使用
 
-示例 A（推荐）：在 RN 工程内用 `fetch` 走 gRPC-Web（二进制），复用本 SDK 的 bufbuild 生成物（不需要重新编译 proto）。这个方案不需要引入 `@improbable-eng/grpc-web-react-native-transport`：
+示例 0（推荐）：直接启用内置 invoker（不需要在 RN 工程维护一套 invoke 代码）：
+
+```ts
+import { initSDK, fetchGuid } from '@goplus123/core-api'
+
+const sdk = initSDK({
+  ws: {
+    url: 'wss://example.com/websocket',
+    protocols: fetchGuid(),
+  },
+  grpc: {
+    baseUrl: 'https://example.com/cms',
+    protocol: 'grpc-web',
+    invoker: 'builtin',
+  },
+  http: {
+    baseUrl: 'https://example.com/api',
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+  defaultTransport: 'auto',
+})
+```
+
+示例 A（自定义）：在 RN 工程内用 `fetch` 走 gRPC-Web（二进制），复用本 SDK 的 bufbuild 生成物（不需要重新编译 proto）。这个方案不需要引入 `@improbable-eng/grpc-web-react-native-transport`：
 
 ```ts
 import { initSDK, fetchGuid } from '@goplus123/core-api'
@@ -352,6 +390,49 @@ function capitalizeRpcName(methodName: string): string {
   return methodName[0]!.toUpperCase() + methodName.slice(1)
 }
 
+function resolveServiceMethod(service: any, methodName: string, method?: any): any | undefined {
+  if (method) return method
+
+  const expectedLocalName = methodName
+  const expectedRpcName = capitalizeRpcName(methodName)
+
+  const direct = service?.method
+  if (Array.isArray(direct)) {
+    return direct.find((m: any) => {
+      const localName = String(m?.localName ?? '')
+      const rpcName = String(m?.name ?? '')
+      return (
+        localName === expectedLocalName ||
+        localName === expectedRpcName ||
+        rpcName === expectedLocalName ||
+        rpcName === expectedRpcName
+      )
+    })
+  }
+  if (direct && typeof direct === 'object') {
+    return (direct as any)[expectedLocalName] ?? (direct as any)[expectedRpcName]
+  }
+
+  const methods = service?.methods
+  if (Array.isArray(methods)) {
+    return methods.find((m: any) => {
+      const localName = String(m?.localName ?? '')
+      const rpcName = String(m?.name ?? '')
+      return (
+        localName === expectedLocalName ||
+        localName === expectedRpcName ||
+        rpcName === expectedLocalName ||
+        rpcName === expectedRpcName
+      )
+    })
+  }
+  if (methods && typeof methods === 'object') {
+    return (methods as any)[expectedLocalName] ?? (methods as any)[expectedRpcName]
+  }
+
+  return undefined
+}
+
 function getGrpcWebPath(service: any, methodName: string, method: any): string {
   const typeName = String(service?.typeName ?? '')
   const rpcName = String(method?.name ?? method?.rpc?.name ?? '') || capitalizeRpcName(methodName)
@@ -367,14 +448,7 @@ async function rnGrpcWebUnary(args: {
   headers: Record<string, string>
   callOptions?: { timeoutMs?: number }
 }): Promise<any> {
-  const method =
-    args.method ??
-    (() => {
-      const ms = args.service?.methods
-      if (Array.isArray(ms)) return ms.find((m: any) => m?.localName === args.methodName || m?.name === args.methodName)
-      if (ms && typeof ms === 'object') return (ms as any)[args.methodName]
-      return undefined
-    })()
+  const method = resolveServiceMethod(args.service, args.methodName, args.method)
   if (!method) {
     throw new Error(`gRPC method not found: ${String(args.service?.typeName ?? '')}.${args.methodName}`)
   }
@@ -447,7 +521,10 @@ const sdk = initSDK({
 })
 ```
 
-补充说明：如果你已经在 RN 工程里有基于 `@improbable-eng/grpc-web` / `@improbable-eng/grpc-web-react-native-transport` 的 `rnGrpcWebUnary` 封装，也可以直接把它塞进 `invoker.unary`。但需要确保它能消费本 SDK 生成的 bufbuild message 与 schema（`toBinary/fromBinary`），否则通常会因为“message/descriptor 体系不一致”（improbable 常见搭配是另一套 proto 生成物）而对不上类型与序列化方式。
+补充说明：
+
+- 自定义 invoker 时，建议优先使用 `args.method`（SDK 解析好的方法描述），避免在 RN 侧重复解析 `service.method/service.methods` 的结构差异。
+- 如果你已经在 RN 工程里有基于 `@improbable-eng/grpc-web` / `@improbable-eng/grpc-web-react-native-transport` 的 `rnGrpcWebUnary` 封装，也可以直接把它塞进 `invoker.unary`。但需要确保它能消费本 SDK 生成的 bufbuild message 与 schema（`toBinary/fromBinary`），否则通常会因为“message/descriptor 体系不一致”（improbable 常见搭配是另一套 proto 生成物）而对不上类型与序列化方式。
 
 ### 2) 直接调用（推荐）