واجهة التاريخ والوقت

Instant والوقت الآلي

15 دقيقة الدرس 3 من 13

Instant والوقت الآلي

يدور معظم واجهة برمجة java.time حول الوقت البشري — التقاويم والمناطق الزمنية والأشهر وأيام الأسبوع. لكن الحواسيب والأنظمة الموزّعة تحتاج في الغالب إلى شيء أبسط: رقم واحد يُحدّد نقطة بلا غموض على الجدول الزمني العالمي. هذا بالضبط ما توفّره Instant.

حقبة يونيكس ومعنى "الوقت الآلي"

بالاتفاق الدولي، يُقاس الوقت على الحواسيب من حقبة يونيكس: منتصف الليل بتوقيت UTC في الأول من يناير 1970 (1970-01-01T00:00:00Z). كل لحظة في التاريخ تُعبَّر عنها كعدد موقّع من الثواني (وأجزائها) نسبةً إلى هذه النقطة المرجعية.

الوقت الآلي خالٍ من المناطق الزمنية ومن اللغات المحلية ومن التقاويم. لا يوجد فيه مفهوم "الثلاثاء" أو "مارس" — مجرّد رقم على خط الأرقام. هذا يجعله مثاليًا لـ:

  • ختم سجلات التتبع وسجلات التدقيق بالطابع الزمني
  • قياس الوقت المنقضي في اختبارات الأداء
  • مقارنة الأحداث عبر الأنظمة الموزّعة في مناطق جغرافية مختلفة
  • تخزين الوقت ونقله في قواعد البيانات وواجهات JSON البرمجية

الصنف Instant

تمثّل java.time.Instant نقطة على الجدول الزمني بدقة تصل إلى النانوثانية. داخليًا تحتفظ بحقلين: long epochSecond (الثواني منذ 1970-01-01T00:00:00Z) وint nanos (التعديل بالنانوثانية داخل تلك الثانية، من 0 إلى 999,999,999).

import java.time.Instant; Instant now = Instant.now(); // اللحظة الحالية بتوقيت UTC Instant epoch = Instant.EPOCH; // 1970-01-01T00:00:00Z Instant future = Instant.MAX; // علامة المستقبل البعيد Instant past = Instant.MIN; // علامة الماضي البعيد System.out.println(now); // مثال: 2026-06-09T07:42:00.123456789Z System.out.println(now.getEpochSecond()); // الثواني منذ الحقبة System.out.println(now.getNano()); // النانوثانية ضمن الثانية
الحرف Z في النهاية ليس اختياريًا. تنتهي دائمًا نتيجة toString() لأي Instant بالحرف Z (زولو، الرمز الصوتي لحرف Z في مقياس NATO)، وهو يعني UTC. هذا هو تمثيل ISO-8601 لطابع زمني بتوقيت UTC. حين تُرسل أو تستقبل طوابع زمنية في واجهات برمجية، يُشير Z إلى أن التوقيت بالفعل بتوقيت UTC ولا يحتاج إلى تحويل.

إنشاء كائنات Instant

إضافةً إلى Instant.now() توجد عدة توابع مصنع:

// من ثانية-حقبة + تعديل بالنانوثانية Instant t1 = Instant.ofEpochSecond(1_000_000_000L); // 2001-09-09T01:46:40Z Instant t2 = Instant.ofEpochSecond(1_000_000_000L, 500_000_000); // + 500 مللي ثانية // من الميلي ثانية-حقبة (شائع عند قراءة System.currentTimeMillis()) Instant t3 = Instant.ofEpochMilli(System.currentTimeMillis()); // من سلسلة نصية (ISO-8601 مع Z أو إزاحة صريحة) Instant t4 = Instant.parse("2024-01-15T09:30:00Z");

الاستعلام عن Instant

Instant t = Instant.parse("2024-01-15T09:30:00.250Z"); long sec = t.getEpochSecond(); // 1705311000 int nano = t.getNano(); // 250_000_000 (250 مللي ثانية معبّرًا عنها بالنانوثانية) long ms = t.toEpochMilli(); // 1705311000250
فضّل toEpochMilli() عند التكامل مع الكود القديم (طوابع JDBC الزمنية، Date، المكتبات الخارجية) لأن دقة الميلي ثانية هي القاسم المشترك. لا تلجأ إلى getNano() إلا حين تحتاج فعلًا إلى دقة أدق من الميلي ثانية.

الوقت الآلي مقابل الوقت البشري: لماذا يهم الفرق؟

فكّر في تخزين موعد لمستخدم. إذا خزّنته كـInstant التقطت نقطة الوقت بتوقيت UTC، لكنك ستفقد القصد: المستخدم قال "9 صباحًا في نيويورك" — وإذا حدث تحوّل في التوقيت الصيفي قبل الموعد، فإن 9 صباحًا بتوقيت UTC لن يكون بعدها 9 صباحًا بالتوقيت المحلي. هذه مشكلة وقت بشري.

في المقابل، إذا خزّنت حدثًا في سجل موزّع كـZonedDateTime بالتوقيت المحلي للخادم، وكان هذا الخادم في منطقة مختلفة عن خادم آخر، يصبح ربط الأحداث بين السجلَّين تمرينًا مؤلمًا في تحويل المناطق الزمنية. هذه مشكلة يحلّها Instant بسهولة تامة.

القاعدة العملية:

  • استخدم Instant لـ: طوابع السجلات والتدقيق وترتيب الأحداث بين الخدمات وقياس المدد وتخزين "متى حدث هذا بمصطلحات مطلقة".
  • استخدم ZonedDateTime / LocalDateTime لـ: التقاويم والجدولة وكل ما يراه المستخدم ويستدلّ عليه بتوقيته المحلي.

العمليات الحسابية على Instant

تدعم Instant الجمع والطرح عبر Duration (سيأتي في الدرس التالي)، إضافةً إلى توابع مختصرة للوحدات الشائعة:

import java.time.Instant; import java.time.Duration; import java.time.temporal.ChronoUnit; Instant start = Instant.now(); Instant oneHourLater = start.plus(Duration.ofHours(1)); Instant tenSecsEarlier = start.minus(10, ChronoUnit.SECONDS); Instant thirtyMsLater = start.plusMillis(30); System.out.println(start.isBefore(oneHourLater)); // true System.out.println(start.isAfter(tenSecsEarlier)); // true // قياس الوقت المنقضي بدقة Instant before = Instant.now(); Thread.sleep(50); Instant after = Instant.now(); long elapsed = Duration.between(before, after).toMillis(); System.out.println("المنقضي: " + elapsed + " ms"); // ~50
لا تستخدم Instant لاختبارات الأداء الدقيقة. تقرأ Instant.now() ساعة الحائط للنظام، التي يمكن أن تقفز للخلف أثناء تصحيحات NTP. لاختبار الأداء عالي الدقة استخدم System.nanoTime() — فهو رتيب (لا يرجع أبدًا للخلف) لكنه لا يحمل معنى حقبة ولا يمكن تحويله إلى تاريخ. استخدم Instant حين تحتاج طابعًا زمنيًا حقيقيًا لساعة الحائط؛ واستخدم System.nanoTime() حين تحتاج فقط قياس مدة.

التحويل بين Instant والأنواع المقروءة للإنسان

ستحتاج كثيرًا إلى تحويل Instant إلى تمثيل زمني محلّي أو بمنطقة زمنية محدّدة للعرض، أو التحويل في الاتجاه المعاكس بعد إدخال المستخدم:

import java.time.*; Instant instant = Instant.now(); ZoneId ny = ZoneId.of("America/New_York"); // Instant → ZonedDateTime ZonedDateTime zdt = instant.atZone(ny); System.out.println(zdt); // 2026-06-09T03:42:00.123-04:00[America/New_York] // ZonedDateTime → Instant Instant back = zdt.toInstant(); // OffsetDateTime (إزاحة ثابتة بلا قواعد توقيت صيفي) OffsetDateTime odt = instant.atOffset(ZoneOffset.UTC);

Instant وواجهات برمجة الإصدارات القديمة

قبل Java 8 كان العالم يستخدم java.util.Date وjava.sql.Timestamp. ستصادف هذين الصنفين في قواعد الكود القديمة وتعريفات JDBC وتعيينات ORM. الجسر بينهما مباشر:

import java.time.Instant; import java.util.Date; import java.sql.Timestamp; // java.util.Date ↔ Instant Date legacyDate = Date.from(Instant.now()); Instant fromDate = legacyDate.toInstant(); // java.sql.Timestamp ↔ Instant Timestamp ts = Timestamp.from(Instant.now()); Instant fromTs = ts.toInstant();

الخلاصة

Instant هو تمثيل java.time للوقت الآلي: نقطة على الجدول الزمني بتوقيت UTC خالية من المناطق الزمنية والتقاويم، مقيسة من حقبة يونيكس. استخدمها في كل مكان تحتاج فيه طابعًا زمنيًا عالميًا لا لبس فيه — التسجيل وترتيب الأحداث والتخزين والتواصل بين الخدمات. لأي شيء يقرأه الإنسان أو يجدوله بتوقيته المحلي، حوّل إلى ZonedDateTime. سيقدّم الدرس التالي Duration وPeriod، الصنفَين اللذَين يمثّلان امتداد الزمن.

الدرس السابق LocalDate وLocalTime وLocalDateTime
الدرس التالي المُدد الزمنية: Duration و Period
العودة للدورة