OpenRPC方法

JSON-RPC 方法

使用参数、结果和错误处理来记录 JSON-RPC 方法

以 Markdown 格式查看

OpenRPC 中的方法是 JSON-RPC API 的核心构建块。每个方法都定义了过程名称、参数、返回值和潜在错误。

openrpc.yml
1methods:
2  - name: user.create
3    summary: Create a new user
4    description: Creates a new user account with the provided information
5    params:
6      - name: userData
7        schema:
8          $ref: '#/components/schemas/CreateUserRequest'
9        required: true
10        description: User data for account creation
11    result:
12      name: createdUser
13      schema:
14        $ref: '#/components/schemas/User'
15      description: The newly created user object
16    examples:
17      - name: CreateUserExample
18        description: Example of creating a user
19        params:
20          userData:
21            email: "john@example.com"
22            name: "John Doe"
23            age: 30
24        result:
25          id: "user_123"
26          email: "john@example.com"
27          name: "John Doe"
28          age: 30
29          createdAt: "2024-01-15T10:30:00Z"

方法参数

JSON-RPC 中的参数可以是位置参数（按位置）或命名参数（按名称）：

命名参数

openrpc.yml
1methods:
2  - name: calculate.add
3    summary: Add two numbers
4    paramStructure: by-name
5    params:
6      - name: a
7        schema:
8          type: number
9        required: true
10        description: First number
11      - name: b
12        schema:
13          type: number
14        required: true
15        description: Second number
16    result:
17      name: sum
18      schema:
19        type: number

位置参数

openrpc.yml
1methods:
2  - name: calculate.multiply
3    summary: Multiply two numbers
4    paramStructure: by-position
5    params:
6      - schema:
7          type: number
8        description: First number (multiplicand)
9      - schema:
10          type: number
11        description: Second number (multiplier)
12    result:
13      name: product
14      schema:
15        type: number

复杂参数类型

为方法参数使用复杂的模式：

openrpc.yml
1methods:
2  - name: order.create
3    summary: Create a new order
4    description: Creates a new order with items and shipping information
5    params:
6      - name: orderData
7        schema:
8          type: object
9          properties:
10            items:
11              type: array
12              items:
13                $ref: '#/components/schemas/OrderItem'
14              minItems: 1
15            shippingAddress:
16              $ref: '#/components/schemas/Address'
17            paymentMethod:
18              type: string
19              enum: [credit_card, paypal, bank_transfer]
20            notes:
21              type: string
22              maxLength: 500
23          required:
24            - items
25            - shippingAddress
26            - paymentMethod
27        required: true
28    result:
29      name: order
30      schema:
31        $ref: '#/components/schemas/Order'

方法结果

定义成功方法响应的结构：

openrpc.yml
1methods:
2  - name: search.products
3    summary: Search for products
4    params:
5      - name: query
6        schema:
7          type: string
8        required: true
9    result:
10      name: searchResults
11      schema:
12        type: object
13        properties:
14          products:
15            type: array
16            items:
17              $ref: '#/components/schemas/Product'
18          totalCount:
19            type: integer
20          hasMore:
21            type: boolean
22          nextCursor:
23            type: string
24        required:
25          - products
26          - totalCount
27          - hasMore

错误处理

为您的方法定义自定义错误：

openrpc.yml
1methods:
2  - name: user.login
3    summary: Authenticate user
4    params:
5      - name: email
6        schema:
7          type: string
8          format: email
9        required: true
10    errors:
11      - code: -32001
12        message: Invalid credentials
13        data:
14          type: object
15          properties:
16            error:
17              type: string
18              const: "Email or password is incorrect"
19      - code: -32002
20        message: Account locked
21        data:
22          type: object
23          properties:
24            error:
25              type: string
26              const: "Account temporarily locked due to failed login attempts"
27            unlockTime:
28              type: string
29              format: date-time
30    result:
31      name: authResult
32      schema:
33        $ref: '#/components/schemas/AuthToken'

方法示例

提供全面的示例以获得更好的文档：

openrpc.yml
1methods:
2  - name: file.upload
3    summary: Upload a file
4    params:
5      - name: fileData
6        schema:
7          type: object
8          properties:
9            filename:
10              type: string
11            content:
12              type: string
13              format: base64
14            mimeType:
15              type: string
16        required: true
17    examples:
18      - name: ImageUpload
19        description: Upload a JPEG image
20        params:
21          fileData:
22            filename: "photo.jpg"
23            content: "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwC/gA=="
24            mimeType: "image/jpeg"
25        result:
26          fileId: "file_abc123"
27          url: "https://cdn.example.com/files/file_abc123.jpg"
28          size: 1024000
29      - name: DocumentUpload
30        description: Upload a PDF document
31        params:
32          fileData:
33            filename: "document.pdf"
34            content: "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCgoyIDAgb2JqCjw8Ci9UeXBlIC9QYWdlcwo="
35            mimeType: "application/pdf"
36        result:
37          fileId: "file_def456"
38          url: "https://cdn.example.com/files/file_def456.pdf"
39          size: 256000

可选参数

定义带有默认值的可选参数：

openrpc.yml
1methods:
2  - name: report.generate
3    summary: Generate a report
4    params:
5      - name: reportType
6        schema:
7          type: string
8          enum: [daily, weekly, monthly, yearly]
9        required: true
10      - name: format
11        schema:
12          type: string
13          enum: [pdf, csv, json]
14          default: pdf
15        required: false
16        description: Output format (defaults to PDF)
17      - name: includeCharts
18        schema:
19          type: boolean
20          default: true
21        required: false
22        description: Include charts in the report
23    result:
24      name: report
25      schema:
26        $ref: '#/components/schemas/Report'

方法是 JSON-RPC API 的基础，提供了一个清晰的契约来说明哪些操作是可用的、它们期望什么数据以及返回什么。