JSON-RPC 方法 | Fern Documentation

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

openrpc.yml

methods:
  - name: user.create
    summary: Create a new user
    description: Creates a new user account with the provided information
    params:
      - name: userData
        schema:
          $ref: '#/components/schemas/CreateUserRequest'
        required: true
        description: User data for account creation
    result:
      name: createdUser
      schema:
        $ref: '#/components/schemas/User'
      description: The newly created user object
    examples:
      - name: CreateUserExample
        description: Example of creating a user
        params:
          userData:
            email: "john@example.com"
            name: "John Doe"
            age: 30
        result:
          id: "user_123"
          email: "john@example.com"
          name: "John Doe"
          age: 30
          createdAt: "2024-01-15T10:30:00Z"

方法参数

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

命名参数

openrpc.yml

methods:
  - name: calculate.add
    summary: Add two numbers
    paramStructure: by-name
    params:
      - name: a
        schema:
          type: number
        required: true
        description: First number
      - name: b
        schema:
          type: number
        required: true
        description: Second number
    result:
      name: sum
      schema:
        type: number

位置参数

openrpc.yml

methods:
  - name: calculate.multiply
    summary: Multiply two numbers
    paramStructure: by-position
    params:
      - schema:
          type: number
        description: First number (multiplicand)
      - schema:
          type: number
        description: Second number (multiplier)
    result:
      name: product
      schema:
        type: number

复杂参数类型

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

openrpc.yml

methods:
  - name: order.create
    summary: Create a new order
    description: Creates a new order with items and shipping information
    params:
      - name: orderData
        schema:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/OrderItem'
              minItems: 1
            shippingAddress:
              $ref: '#/components/schemas/Address'
            paymentMethod:
              type: string
              enum: [credit_card, paypal, bank_transfer]
            notes:
              type: string
              maxLength: 500
          required:
            - items
            - shippingAddress
            - paymentMethod
        required: true
    result:
      name: order
      schema:
        $ref: '#/components/schemas/Order'

方法结果

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

openrpc.yml

methods:
  - name: search.products
    summary: Search for products
    params:
      - name: query
        schema:
          type: string
        required: true
    result:
      name: searchResults
      schema:
        type: object
        properties:
          products:
            type: array
            items:
              $ref: '#/components/schemas/Product'
          totalCount:
            type: integer
          hasMore:
            type: boolean
          nextCursor:
            type: string
        required:
          - products
          - totalCount
          - hasMore

错误处理

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

openrpc.yml

methods:
  - name: user.login
    summary: Authenticate user
    params:
      - name: email
        schema:
          type: string
          format: email
        required: true
    errors:
      - code: -32001
        message: Invalid credentials
        data:
          type: object
          properties:
            error:
              type: string
              const: "Email or password is incorrect"
      - code: -32002
        message: Account locked
        data:
          type: object
          properties:
            error:
              type: string
              const: "Account temporarily locked due to failed login attempts"
            unlockTime:
              type: string
              format: date-time
    result:
      name: authResult
      schema:
        $ref: '#/components/schemas/AuthToken'

方法示例

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

openrpc.yml

methods:
  - name: file.upload
    summary: Upload a file
    params:
      - name: fileData
        schema:
          type: object
          properties:
            filename:
              type: string
            content:
              type: string
              format: base64
            mimeType:
              type: string
        required: true
    examples:
      - name: ImageUpload
        description: Upload a JPEG image
        params:
          fileData:
            filename: "photo.jpg"
            content: "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwC/gA=="
            mimeType: "image/jpeg"
        result:
          fileId: "file_abc123"
          url: "https://cdn.example.com/files/file_abc123.jpg"
          size: 1024000
      - name: DocumentUpload
        description: Upload a PDF document
        params:
          fileData:
            filename: "document.pdf"
            content: "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCgoyIDAgb2JqCjw8Ci9UeXBlIC9QYWdlcwo="
            mimeType: "application/pdf"
        result:
          fileId: "file_def456"
          url: "https://cdn.example.com/files/file_def456.pdf"
          size: 256000

可选参数

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

openrpc.yml

methods:
  - name: report.generate
    summary: Generate a report
    params:
      - name: reportType
        schema:
          type: string
          enum: [daily, weekly, monthly, yearly]
        required: true
      - name: format
        schema:
          type: string
          enum: [pdf, csv, json]
          default: pdf
        required: false
        description: Output format (defaults to PDF)
      - name: includeCharts
        schema:
          type: boolean
          default: true
        required: false
        description: Include charts in the report
    result:
      name: report
      schema:
        $ref: '#/components/schemas/Report'

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