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

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

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

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

  • graphql وgrpc وmcp, a2a تستخدم 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: {}
      responses:
        "200":
          description: Operation response

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: {}
      responses:
        "200":
          description: Operation response

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
      responses:
        "200":
          description: Operation response

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: {}
      responses:
        "200":
          description: Operation response

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

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

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

لماذا يهم​

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

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

A2A​

يدعم A2A 1.0 تصحيح JSON-RPC وREST وgRPC لسطح المكتب وتوثيقها، إضافةً إلى إنشاء خادم موائم رسائل عديم الحالة. أما المهام الدائمة والتسليم عبر الإشعارات الفورية فتتطلب تنفيذاً خاصاً بك.

استخدم x-protocol: a2a وx-a2a لتصميم رسائل الوكلاء والمهام وتصحيحها وتوثيقها. يدعم A2A 1.0 وسائل JSON-RPC وREST وgRPC لسطح المكتب، ويدعم 0.3 JSON-RPC. راجع وكلاء A2A للامتدادات والتحقق من التوقيع وإنشاء الخادم والمثال القابل للتشغيل.