> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJlMzNiYTAyMS05NzA1LTQ1ODQtYjI2NS1jN2U3YzBlZGI3NDQiLCJleHAiOjE3Nzg0OTM2MzQsImlhdCI6MTc3ODQ5MzMzNH0.5LcGOThSloQB8m16-CX_1M5al0IBdjIYj2fH_lGPYHA
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# JSON-RPC 方法

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

```yml title="openrpc.yml" {2-19}
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 中的参数可以是位置参数（按位置）或命名参数（按名称）：

### 命名参数

```yml title="openrpc.yml" {4-14}
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
```

### 位置参数

```yml title="openrpc.yml" {4-12}
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
```

## 复杂参数类型

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

```yml title="openrpc.yml" {6-24}
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'
```

## 方法结果

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

```yml title="openrpc.yml" {8-20}
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
```

## 错误处理

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

```yml title="openrpc.yml" {10-24}
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'
```

## 方法示例

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

```yml title="openrpc.yml" {12-35}
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
```

## 可选参数

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

```yml title="openrpc.yml" {6-19}
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 的基础，提供了一个清晰的契约来说明哪些操作是可用的、它们期望什么数据以及返回什么。