OpenRPC扩展

SDK 方法名称

以 Markdown 格式查看

默认情况下，Fern 基于您的 OpenRPC 方法名称生成 SDK 方法名称。您可以使用 x-fern-sdk-method-name 扩展来覆盖此行为。

自定义方法名称

使用 x-fern-sdk-method-name 为您的 JSON-RPC 方法指定自定义方法名称：

openrpc.yml
1methods:
2  - name: user.getById
3    summary: Get user by ID
4    x-fern-sdk-method-name: getUser
5    params:
6      - name: id
7        schema:
8          type: string
9        required: true
10    result:
11      name: user
12      schema:
13        $ref: '#/components/schemas/User'
14  - name: order.createNew
15    summary: Create a new order
16    x-fern-sdk-method-name: create
17    params:
18      - name: orderData
19        schema:
20          $ref: '#/components/schemas/CreateOrderRequest'
21        required: true
22    result:
23      name: order
24      schema:
25        $ref: '#/components/schemas/Order'

这将生成如下的 SDK 方法：

1// 代替 client.user.getById()
2const user = await client.user.getUser({ id: "user_123" });
3
4// 代替 client.order.createNew()
5const order = await client.order.create({ orderData: {...} });

方法命名约定

在命名 SDK 方法时遵循这些约定：

CRUD 操作

使用标准的 CRUD 命名：

openrpc.yml
1methods:
2  - name: user.createUser
3    summary: Create a new user
4    x-fern-sdk-method-name: create
5    # 生成: client.user.create()
6    
7  - name: user.getUserById
8    summary: Get user by ID
9    x-fern-sdk-method-name: get
10    # 生成: client.user.get()
11    
12  - name: user.updateUser
13    summary: Update user information
14    x-fern-sdk-method-name: update
15    # 生成: client.user.update()
16    
17  - name: user.deleteUser
18    summary: Delete a user
19    x-fern-sdk-method-name: delete
20    # 生成: client.user.delete()

列表操作

为列表操作使用描述性名称：

openrpc.yml
1methods:
2  - name: user.getAllUsers
3    summary: Get all users
4    x-fern-sdk-method-name: list
5    # 生成: client.user.list()
6    
7  - name: user.searchUsers
8    summary: Search for users
9    x-fern-sdk-method-name: search
10    # 生成: client.user.search()
11    
12  - name: order.getUserOrders
13    summary: Get orders for a user
14    x-fern-sdk-method-name: listByUser
15    # 生成: client.order.listByUser()

动作操作

使用面向动作的名称：

openrpc.yml
1methods:
2  - name: email.sendNotification
3    summary: Send email notification
4    x-fern-sdk-method-name: send
5    # 生成: client.email.send()
6    
7  - name: payment.processPayment
8    summary: Process a payment
9    x-fern-sdk-method-name: process
10    # 生成: client.payment.process()
11    
12  - name: cache.invalidateCache
13    summary: Invalidate cache entries
14    x-fern-sdk-method-name: invalidate
15    # 生成: client.cache.invalidate()

特定语言的方法名称

您可以为不同的编程语言指定不同的方法名称：

openrpc.yml
1methods:
2  - name: user.getUserPreferences
3    summary: Get user preferences
4    x-fern-sdk-method-name:
5      python: get_preferences
6      typescript: getPreferences
7      go: GetPreferences
8      java: getPreferences
9      csharp: GetPreferences
10    params:
11      - name: userId
12        schema:
13          type: string
14        required: true
15    result:
16      name: preferences
17      schema:
18        $ref: '#/components/schemas/UserPreferences'

命名空间方法名称

对于带有命名空间前缀的方法，自定义最终的方法名称：

openrpc.yml
1methods:
2  - name: analytics.track.pageView
3    summary: Track page view event
4    x-fern-sdk-method-name: trackPageView
5    params:
6      - name: eventData
7        schema:
8          $ref: '#/components/schemas/PageViewEvent'
9        required: true
10  - name: analytics.track.conversion
11    summary: Track conversion event
12    x-fern-sdk-method-name: trackConversion
13    params:
14      - name: eventData
15        schema:
16          $ref: '#/components/schemas/ConversionEvent'
17        required: true

生成：

1await client.analytics.trackPageView({ eventData: {...} });
2await client.analytics.trackConversion({ eventData: {...} });

通知方法名称

对于通知方法（单向调用），使用适当的命名：

openrpc.yml
1methods:
2  - name: log.recordError
3    summary: Record an error event
4    x-fern-sdk-method-name: logError
5    params:
6      - name: errorData
7        schema:
8          $ref: '#/components/schemas/ErrorData'
9        required: true
10    # 无结果 - 这是一个通知
11  - name: metrics.incrementCounter
12    summary: Increment a metric counter
13    x-fern-sdk-method-name: increment
14    params:
15      - name: metric
16        schema:
17          type: string
18        required: true
19      - name: value
20        schema:
21          type: number
22          default: 1
23    # 无结果 - 这是一个通知

异步方法命名

对于返回 promise 或 future 的方法，考虑异步命名：

openrpc.yml
1methods:
2  - name: report.generateReport
3    summary: Generate a report (long-running)
4    x-fern-sdk-method-name: generateAsync
5    params:
6      - name: reportConfig
7        schema:
8          $ref: '#/components/schemas/ReportConfig'
9        required: true
10    result:
11      name: jobId
12      schema:
13        type: string
14        description: Job ID for tracking report generation

这确保方法名称遵循每个目标语言的约定，同时为开发者维护清晰直观的 API。