إنتقل إلى المحتوى الرئيسي

البروتوكولات

الأنظمة الفعلية ليست REST فقط. ينمذج Powerduck ستة بروتوكولات في مدخلات مسار OpenAPI عادية عبر امتداد x-protocol. تعيش عمليات البث وRPC في المواصفة نفسها كـREST، بلا أداة منفصلة ولا تحويل قسري إلى أشكال REST.

تبقى كل عملية غير HTTP مدخل مسار عادياً بطريقة HTTP وresponses."200".description.

  • graphql وgrpc وmcp تستخدم post.
  • sse وwebsocket تستخدم عادة get.
  • http هي القيمة الافتراضية ويُحذَف x-protocol.

SSE​

أحداث الخادم المُرسَلة عبر HTTP تستخدم x-protocol: "sse". نوع وسائط البث هو text/event-stream، وتصف حمولة الحدث الفردي بـitemSchema لا schema.

paths:
  /events:
    get:
      x-protocol: sse
      responses:
        "200":
          description: Event stream
          content:
            text/event-stream:
              itemSchema:
                type: object
                properties:
                  type:
                    type: string
                  data:
                    type: string

WebSocket​

يستخدم WebSocket x-protocol: "websocket" مع كتلة x-websocket. يجب أن يبدأ الرابط بـws:// أو wss://.

paths:
  /ws:
    get:
      x-protocol: websocket
      x-websocket:
        url: wss://example.com/ws
        subprotocols: []
        headers: {}

subprotocols وheaders اختياريان.

GraphQL​

يستخدم GraphQL post على مسار بصيغة /graphql/query/fieldName مع x-graphql. نقطة النهاية رابط HTTP(S) مطلق والاستعلام إلزامي.

paths:
  /graphql/query/product:
    post:
      x-protocol: graphql
      x-graphql:
        endpoint: https://example.com/graphql
        query: query Product($id: ID!) { product(id: ID!) { id name } }
        operationName: Product
        variablesSchema:
          type: object
        variables: {}

operationName وvariablesSchema وvariables اختيارية.

gRPC​

يستخدم gRPC post على مسار بصيغة /grpc/pkg.Service/Method مع x-grpc. إذا كان الخادم يدعم الانعكاس، ضع reflection: true؛ وإلا زوّد protoPaths (واختيارياً includeDirs).

paths:
  /grpc/products.ProductService/GetProduct:
    post:
      x-protocol: grpc
      x-grpc:
        address: host:port
        service: products.ProductService
        method: GetProduct
        kind: unary
        reflection: true

kind هي unary أو server_streaming أو client_streaming أو bidi_streaming.

MCP​

يستخدم MCP افتراضياً Streamable HTTP، post على مسار بصيغة /mcp/tools/tool-name، مع كتلة x-mcp.

paths:
  /mcp/tools/create-product:
    post:
      x-protocol: mcp
      x-mcp:
        endpoint: http://127.0.0.1:3000/mcp
        transport: streamable-http
        method: tools/call
        name: create-product
        argumentsSchema:
          type: object
        arguments: {}

يختار method عملية MCP: tools/call وtools/list وresources/read وresources/list وresources/templates/list وprompts/get وprompts/list. يُستخدَم name وuri وargumentsSchema وarguments حسب العملية.

قواعد بنيوية​

  • كل نوع وسائط في requestBody أو responses يحتاج schema أو $ref، باستثناء text/event-stream مع itemSchema.
  • كل معامل يحتاج schema (أو content).
  • عند تعديل عملية، يُحفَظ البروتوكول والضبط المختاران: لا تتحول عمليات RPC أو البث إلى REST صامتاً.
  • استخدم أشكال الامتداد الدقيقة أعلاه؛ لا تخترع مفاتيح مثل externalUrl ولا تستخدم ws كاسم بروتوكول.

لماذا يهم​

عند نمذجة ستة بروتوكولات في مستند واحد، يُدفَع التصميم والتصحيح والمحاكاة والتوثيق وMCP من المصدر نفسه بغض النظر عن النقل. اطلب من المساعد إضافة واجهة بث أو RPC فيُحفَظ ضبط بروتوكولها بدل تسويته إلى REST.

انظر أيضاً: التصميم مع المساعد、نموذج البيانات.