OpenRPC

服务器

为您的 JSON-RPC API 定义服务器 URL 和传输机制

以 Markdown 格式查看

OpenRPC 允许您指定一个或多个服务器配置，定义客户端如何连接到您的 JSON-RPC API。

openrpc.yml
1servers:
2  - name: production
3    url: https://api.yourcompany.com/rpc
4    description: Production HTTP JSON-RPC server
5  - name: websocket
6    url: wss://api.yourcompany.com/rpc
7    description: Production WebSocket JSON-RPC server

指定服务器对于 SDK 和文档都很有价值：

  • 对于 SDK，您的用户无需在客户端实例化时手动指定服务器 URL
  • 对于文档，您的 API playground 将自动连接到正确的服务器

传输协议

JSON-RPC 可以通过各种传输协议使用：

HTTP/HTTPS 传输

openrpc.yml
1servers:
2  - name: http-production
3    url: https://api.yourcompany.com/rpc
4    description: HTTPS JSON-RPC endpoint
5  - name: http-staging
6    url: https://staging-api.yourcompany.com/rpc
7    description: Staging HTTPS endpoint

WebSocket 传输

openrpc.yml
1servers:
2  - name: websocket-production
3    url: wss://api.yourcompany.com/rpc
4    description: WebSocket JSON-RPC for real-time communication
5  - name: websocket-dev
6    url: ws://localhost:8080/rpc
7    description: Development WebSocket server

TCP 传输

openrpc.yml
1servers:
2  - name: tcp-production
3    url: tcp://api.yourcompany.com:9090
4    description: TCP JSON-RPC server for high-performance applications

服务器变量

使用变量使您的服务器配置更加灵活：

openrpc.yml
1servers:
2  - name: production
3    url: https://{environment}.api.yourcompany.com/rpc
4    description: Production JSON-RPC server
5    variables:
6      environment:
7        default: prod
8        enum:
9          - prod
10          - staging
11          - dev
12        description: Environment name

多环境配置

配置不同的环境并提供适当的描述：

openrpc.yml
1servers:
2  - name: production
3    url: https://api.yourcompany.com/rpc
4    description: Production environment - high availability, rate limited
5  - name: staging
6    url: https://staging-api.yourcompany.com/rpc
7    description: Staging environment - for testing new features
8  - name: development
9    url: http://localhost:8080/rpc
10    description: Local development server
11  - name: sandbox
12    url: https://sandbox-api.yourcompany.com/rpc
13    description: Sandbox environment - safe for testing

服务器特定配置

添加服务器特定的元数据和配置：

openrpc.yml
1servers:
2  - name: production
3    url: https://api.yourcompany.com/rpc
4    description: Production JSON-RPC server
5    variables:
6      version:
7        default: v1
8        enum: [v1, v2]
9        description: API version
10    summary: High-performance production server
11    tags:
12      - name: production
13        description: Production environment

负载均衡和多个 URL

为负载均衡配置多个服务器 URL：

openrpc.yml
1servers:
2  - name: primary
3    url: https://api-primary.yourcompany.com/rpc
4    description: Primary production server
5  - name: secondary
6    url: https://api-secondary.yourcompany.com/rpc
7    description: Secondary production server (fallback)
8  - name: regional-us
9    url: https://us.api.yourcompany.com/rpc
10    description: US regional server
11  - name: regional-eu
12    url: https://eu.api.yourcompany.com/rpc
13    description: EU regional server

WebSocket 特定配置

配置带有连接参数的 WebSocket 服务器：

openrpc.yml
1servers:
2  - name: websocket-main
3    url: wss://api.yourcompany.com/rpc
4    description: Main WebSocket JSON-RPC server
5    variables:
6      protocol:
7        default: "jsonrpc-2.0"
8        description: JSON-RPC protocol version
9      heartbeat:
10        default: "30"
11        description: Heartbeat interval in seconds

安全配置

在服务器级别配置身份验证和安全性：

openrpc.yml
1servers:
2  - name: secure-production
3    url: https://api.yourcompany.com/rpc
4    description: Secure production server with authentication
5    security:
6      - bearerAuth: []
7      - apiKeyAuth: []
8components:
9  securitySchemes:
10    bearerAuth:
11      type: http
12      scheme: bearer
13    apiKeyAuth:
14      type: apiKey
15      in: header
16      name: X-API-Key

传输特定优化

为特定用例配置服务器：

openrpc.yml
1servers:
2  - name: bulk-operations
3    url: https://bulk.api.yourcompany.com/rpc
4    description: Optimized for batch requests and bulk operations
5  - name: real-time
6    url: wss://realtime.api.yourcompany.com/rpc
7    description: WebSocket server optimized for real-time notifications
8  - name: analytics
9    url: https://analytics.api.yourcompany.com/rpc
10    description: Dedicated server for analytics and reporting methods

服务器配置帮助客户端了解如何连接到您的 JSON-RPC API，以及哪种传输机制最适合他们的用例。