مقدمة

Smart-Doc هي أداة قوية لإنشاء الوثائق تساعد المطورين على إنشاء وثائق API واضحة ومفصلة لمشاريع Java بسهولة. مع تزايد شعبية تقنية WebSocket، أضاف Smart-Doc دعمًا لواجهات WebSocket بدءًا من الإصدار 3.0.7. ستتناول هذه المقالة بالتفصيل كيفية استخدام Smart-Doc لإنشاء وثائق واجهة Java WebSocket وتقديم مثال كامل لخادم WebSocket.

نظرة عامة على تقنية WebSocket

أولاً، دعونا نفهم بإيجاز تقنية WebSocket. يوفر بروتوكول WebSocket قناة اتصال مزدوجة الاتجاه، مما يجعل تبادل البيانات بين العميل والخادم أسهل وأكثر كفاءة. في Java، يمكن للمطورين تنفيذ خوادم وعملاء WebSocket بسهولة باستخدام JSR 356: Java API for WebSocket.

نظرة عامة على التعليقات التوضيحية لـ WebSocket

في Java WebSocket، يتم استخدام التعليق التوضيحي @ServerEndpoint لتعريف فئة POJO كنقطة نهاية لخادم WebSocket. يمكن استدعاء الأساليب المميزة بهذا التعليق التوضيحي تلقائيًا عند حدوث أحداث WebSocket (مثل إنشاء الاتصال واستقبال الرسائل وما إلى ذلك). إلى جانب @ServerEndpoint، هناك العديد من التعليقات التوضيحية الأخرى المتعلقة بـ WebSocket:

1. @OnOpen: يتم تشغيل هذه الطريقة عندما يقوم العميل بإنشاء اتصال WebSocket مع الخادم. يتم استخدامه عادةً لتهيئة الموارد أو إرسال رسالة ترحيب.

2. @OnMessage: يتم تشغيل هذه الطريقة عندما يتلقى الخادم رسالة من العميل. وهي مسؤولة عن معالجة الرسالة المستلمة وتنفيذ العمليات المقابلة لها.

3. @OnClose: يتم تشغيل هذه الطريقة عندما يقوم العميل بإغلاق اتصال WebSocket. يتم استخدامه عادةً لتحرير الموارد أو إجراء أعمال التنظيف.

4. @OnError: يتم تشغيل هذه الطريقة في حالة حدوث خطأ أثناء اتصال WebSocket. يعالج حالات الخطأ، مثل التسجيل أو إخطار المستخدم.

مقدمة إلى Smart-Doc

Smart-Doc هي أداة خفيفة الوزن لإنشاء وثائق API تعتمد على Java. وهو يدعم استخراج معلومات الواجهة من الكود المصدري والتعليقات، وإنشاء الوثائق تلقائيًا بتنسيق Markdown. بالنسبة لمشاريع WebSocket، هذا يعني أنه يمكنك استخراج الوثائق مباشرة من فئات ServerEndpoint الخاصة بك دون كتابة أوصاف وثائق مملة يدويًا.

https://github.com/TongchengOpenSource/smart-doc

تكوين Smart-Doc لإنشاء وثائق واجهة WebSocket

إعداد البيئة

تأكد من تثبيت المكونات التالية في بيئة التطوير الخاصة بك:

• جافا 17 أو أعلى
• Maven أو Gradle كأداة بناء
• أحدث إصدار من البرنامج المساعد Smart-Doc
• مكتبة تنفيذ خادم WebSocket، مثل javax.websocket (عادة ما تكون مضمنة في Java SE)

إنشاء خادم WebSocket

إضافة تبعية البرنامج المساعد

أضف تبعية Smart-Doc في ملف pom.xml:

com.ly.smart-docsmart-doc-maven-plugin[Latest version]./src/main/resources/smart-doc.json

إنشاء نقطة نهاية خادم WebSocket

تحديد نوع الرسالة (Message)، وهي POJO بسيطة تمثل الرسالة المستلمة من العميل.

public class Message {
    private String content;

    // getter and setter methods
}

تحديد نوع الاستجابة (SampleResponse)، وهو POJO بسيط يمثل رسالة الاستجابة المراد إرسالها مرة أخرى إلى العميل.

public class SampleResponse {
    private String responseContent;
    // getter and setter methods
}

تنفيذ وحدة فك ترميز الرسائل (MessageDecoder)، المسؤولة عن تحويل الرسالة المرسلة من قبل العميل من تنسيق JSON إلى كائن رسالة.

public class MessageDecoder implements Decoder.Text {

    private static final ObjectMapper objectMapper = new ObjectMapper();
    @Override
    public Message decode(String s) throws DecodeException {
        try {
            return objectMapper.readValue(s, Message.class);
        } catch (Exception e) {
            throw new DecodeException(s, "Unable to decode text to Message", e);
        }
    }
    @Override
    public boolean willDecode(String s) {
        return (s != null);
    }

    @Override
    public void init(EndpointConfig endpointConfig) {
    }
    @Override
    public void destroy() {
    }
}

تنفيذ برنامج تشفير الاستجابة (MessageResponseEncoder).

public class MessageResponseEncoder implements Encoder.Text {

    private static final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public String encode(SampleResponse response) {
        try {
            return objectMapper.writeValueAsString(response);
        } catch (Exception e) {
            throw new RuntimeException("Unable to encode SampleResponse", e);
        }
    }

    @Override
    public void init(EndpointConfig endpointConfig) {
    }

    @Override
    public void destroy() {
    }
}

استخدم التعليق التوضيحي ServerEndpoint لإنشاء خادم WebSocket بسيط.

/**
 * WebSocket server endpoint example.
 */
@Component
@ServerEndpoint(value = "/ws/chat/{userId}",
        decoders = {MessageDecoder.class},
        encoders = {MessageResponseEncoder.class})
public class ChatEndpoint {

    /**
     * Called when a new connection is established.
     *
     * @param session the client session
     * @param userId  the user ID
     */
    @OnOpen
    public void onOpen(Session session, @PathParam("userId") String userId) {
        System.out.println("Connected: "   session.getId()   ", User ID: "   userId);
    }

    /**
     * Called when a message is received from the client.
     *
     * @param message the message sent by the client
     * @param session the client session
     * @return the response message
     */
    @OnMessage
    public SampleResponse receiveMessage(Message message, Session session) {
        System.out.println("Received message: "   message);
        return new SampleResponse(message.getContent());
    }

    /**
     * Called when the connection is closed.
     *
     * @param session the client session
     */
    @OnClose
    public void onClose(Session session) {
        System.out.println("Disconnected: "   session.getId());
    }

    /**
     * Called when an error occurs.
     *
     * @param session   the client session
     * @param throwable the error
     */
    @OnError
    public void onError(Session session, Throwable throwable) {
        throwable.printStackTrace();
    }
}

تكوين Smart-Doc

قم بإنشاء ملف تكوين Smart-doc.json للسماح لـ Smart-Doc بمعرفة كيفية إنشاء الوثائق.

{
  "serverUrl": "http://smart-doc-demo:8080", // Set the server address, not required
  "outPath": "src/main/resources/static/doc" // Specify the output path of the document
}

توليد الوثائق

قم بتشغيل الأمر التالي في سطر الأوامر لإنشاء الوثائق:

mvn smart-doc:websocket-html

عرض التوثيق

بعد إنشاء الوثائق، يمكنك العثور عليها في الدليل src/main/resources/static/doc/websocket. افتح ملف websocket-index.html في المتصفح لعرض وثائق WebSocket API.

خاتمة

لا يؤدي إنشاء وثائق واجهة Java WebSocket تلقائيًا باستخدام Smart-Doc إلى توفير الكثير من وقت كتابة الوثائق اليدوية فحسب، بل يضمن أيضًا دقة الوثائق وتحديثها في الوقت المناسب. لقد ثبت أن استراتيجية إدارة التوثيق الجيدة يمكن أن تحسن بشكل كبير كفاءة التطوير وجودة الكود. باستخدام أدوات مثل Smart-Doc، يمكنك التركيز بشكل أكبر على تطوير تطبيقات WebSocket دون القلق بشأن مشكلات صيانة الوثائق.