قاعدة واحدة، أسطح متعددة: التحقق كقرار تصميمي
نظرة أولى على Jeninnet.Validation 1.0.0-preview.1
لمحة عن الإصدار:
1.0.0-preview.1· .NET 11 (STS) · C# 15 · 25 حزمة ·
997 اختبارًا · MIT
قاعدة واحدة، محرك واحد، أسطح متعددة. التعريف نفسه يغذي الـ API والواجهة والمخطط والعميل والاختبارات.
افتح أي حل .NET كبير، ثم حاول أن تتبع قاعدة تحقق واحدة. ستجدها في السمة على النموذج، وفي قاعدة
fluent داخل طبقة التطبيق، وفي مصفوفة required داخل وثيقة
OpenAPI، وفي شرط داخل نموذج Blazor، وفي اختبار يعيد كتابة الحدود مرة أخرى.
كل نسخة تبدو معقولة وحدها. مجتمعة، تصنع عقدًا ضمنيًا لا يملكه أحد.
المشكلة ليست أن .NET ينقصه إطار تحقق. المشكلة أن التحقق ما زال يُعامل كتفصيل تنفيذي محلي في كل
طبقة، فتتغير القاعدة أثناء انتقالها: تعليمة nullable تصبح مصفوفة required،
وحدّ طول يصبح minLength وmaxLength، وشرط يصبح تعليقًا
في العميل، ودالة مخصصة تصبح «على الخادم فقط» بالمصادفة.
يبدأ Jeninnet.Validation من فرضية مختلفة: قاعدة التحقق كائن تصميمي. تستحق تعريفًا واحدًا،
ومحرك تنفيذ واحدًا، وعددًا من المستهلكين بقدر ما يحتاجه النظام. ما تبقّى من هذه المقالة يدور حول
ما تجعله هذه الفرضية ممكنًا، وأين تتوقف، وكيف تقرر إن كانت تناسب نظامك.
قاعدة التبعية تنطبق على التحقق أيضًا
كثيرًا ما تُختصر البنية النظيفة في قاعدة واحدة: اتجاه التبعيات نحو الداخل، نحو النطاق. الأطر
تفاصيل. قاعدة البيانات تفصيل. الويب تفصيل.
التحقق عادةً يُستثنى من هذه القاعدة. يظهر في المتحكم كفحص لحالة النموذج، وفي الواجهة كتلميحات
للعميل، وفي وثيقة الـ API كمخطط، وفي النطاق كقيد. فينتهي الأمر بأن يعتمد النطاق على سمات إطار
الويب، أو بأن يملك إطار الويب قواعد لا يستطيع شرحها إلا النطاق.
يأخذ Jeninnet.Validation قاعدة التبعية بجدية. حزمة
Jeninnet.Validation.Abstractions تحتوي العقود وأنواع القيم، ولا تشير إلى أي
إطار. حزمة Jeninnet.Validation تحتوي المحرك وواجهة fluent.
وكل ما عدا ذلك — ASP.NET Core وBlazor وDataAnnotations وMediatR وGraphQL وgRPC وOpenAPI وJSON
Schema — محول اختياري يشير إلى الداخل. مجموعة اختبارات البنية تثبّت هذا الاتجاه.
النتيجة العملية بسيطة: القاعدة نفسها تستطيع أن تعمل في تطبيق console، وفي minimal API، وفي معالج
MediatR، وفي نموذج Blazor، وفي خدمة gRPC، دون أن تُعاد كتابتها لكل مضيف.
namespace MyApp.Models;
using Jeninnet.Validation.Attributes;
[Validate]
public sealed class Customer
{
[NotEmpty, Length(1, 100)]
public string Name { get; init; } = string.Empty;
[NotEmpty, Email]
public string Email { get; init; } = string.Empty;
[InclusiveBetween(18, 120)]
public int Age { get; init; }
}
تطلب السمة [Validate] من مولّد المصدر أن ينتج
CustomerValidator داخل MyApp.Models.Validators.
النوع الناتج يطبّق IValidator<Customer> و
IValidationDescriptorProvider. وهو C# عادي: مقروء، قابل للتنقيح، ويظهر عبر
Go to Definition. لا يوجد تجميع لأشجار التعبير وقت التشغيل، ولا خطوة انعكاس خفية على مسار
التحقق. وتغطي القواعد المضمّنة الحضور والطول والمقارنة والصيغة (البريد وURL وIP وBase64) والتاريخ
والوقت والمجموعات والشروط العابرة للخصائص. وتضيف حزمة النطاق الاختيارية UUID وULID وIBAN وأرقام
VAT والرمز البريدي والهوية الوطنية وسياسة كلمات المرور. ويسرد مرجع القواعد المجموعة الكاملة.
هذه النقطة ليست تفصيلًا أدائيًا ملحقًا بالتصميم. إنها تغيّر ما يمكن الوثوق به. إذا كان المُدقّق
كودًا مولّدًا، يستطيع المنقّح أن يخطو داخله. وإذا كانت البيانات الوصفية واصفًا مجمّدًا، يستطيع
كاتب المخطط أن يستهلكه دون تنفيذ المُدقّق. تصبح القاعدة أثرًا يمكن لأدوات أخرى فحصه.
طريقتان لكتابة القاعدة، ومحرك واحد
الإطار الذي يقدّم السمات وواجهة fluent معًا غالبًا يخفي سرًا صغيرًا: أحد
المسارين هو التنفيذ الحقيقي، والآخر غلاف مريح يتصرف باختلاف طفيف. يرفض Jeninnet.Validation هذا
الانقسام.
مسار السمات هو المسار التصريحي الافتراضي. ومسار fluent هو البديل المدعوم
للقواعد الديناميكية، والدوال التي تحتفظ بحالة ملتقطة، والمُدقّقات التي تحتاج خدمات محقونة.
using Jeninnet.Validation;
using Jeninnet.Validation.Fluent;
using MyApp.Models;
public sealed class CustomerValidator : Validator
{
protected override void Configure(ValidatorRuleBuilder builder)
{
builder.RuleFor(x => x.Name, nameof(Customer.Name))
.NotEmpty()
.Length(1, 100);
builder.RuleFor(x => x.Email, nameof(Customer.Email))
.NotEmpty()
.EmailAddress();
builder.RuleFor(x => x.Age, nameof(Customer.Age))
.InclusiveBetween(18, 120);
}
}
كلا المسارين يطبّق العقد IValidator<T> نفسه، ويغذيان محرك التنفيذ نفسه.
ويثبّت المستودع هذه الدعوى باختبارات تكافؤ تنفيذية: النموذج نفسه، والسيناريوهات نفسها، والنتائج
المتوقعة نفسها. هذا أهم مما يبدو للوهلة الأولى. اختبارات التكافؤ تحوّل «هاتان الواجهتان
متكافئتان» من وثيقة إلى التزام يُفحص عند البناء.
ويحمل مسار fluent ما لا تستطيع السمات التعبير عنه جيدًا:
- قواعد تعتمد على خدمة تُحل من حاوية التبعيات؛
- شروط تغلق على حالة الطلب؛
- مجموعات قواعد تُختار وقت التشغيل بحسب قرار تفويض؛
- قواعد مخصصة تحتاج النموذج وقيمة العضو وسياق التحقق؛
- قوالب قواعد تُضبط مرة وتُستخدم في عدة مُدقّقات.
وتتركّب المُدقّقات أيضًا. تعيد Include استخدام قواعد مُدقّق آخر في الجذر؛
وتضم IncludeBase مُدقّقًا معلنًا لنوع أساسي أو واجهة؛ ويعيد
SetValidator استخدام مُدقّق لخاصية متداخلة؛ ويعرّف
ChildRules قواعد متداخلة في المكان. ويتتبع المولّد الأصناف الأساسية
والواجهات الموسومة في مسار السمات، فالوراثة ليست نموذج تأليف منفصلًا.
وللحالات الواقعة بين المسارين، يعرض المُدقّق المولّد خطافًا جزئيًا اسمه
AddCustomValidators(). الخطاف ضيق عن قصد: يضيف قواعد إلى قوائم القواعد
المولّدة، فيظل المُدقّق الناتج يعمل عبر المحرك نفسه، ويظل ظاهرًا في
Describe().
المترجم هو الاختبار الأول
إطار التحقق الذي لا يفشل إلا وقت التشغيل يكون قد نقل المشكلة، لا حلّها.
تضم حزمة المحللات 33 تشخيصًا نشطًا من عائلة VAL مع إصلاحات آلية. ترفض
إعدادات القواعد غير الصالحة قبل أن يبدأ التطبيق: قاعدة رقمية على عضو نصي، أو نموذج عام مفتوح
سينتج أسماء مولّدة ملتبسة، أو قيمة تاريخ نسبية لا يمكن تحليلها بصورة ثابتة، أو واضع غير متاح
يستخدمه التعقيم، أو شكل نموذج لا يمكن توليده على نحو حتمي.
التشخيصات ليست زينة. إنها الجزء الذي يعبّر عن رأي تصميمي: إذا كانت القاعدة خاطئة، فعلى البناء أن
يقول ذلك. ويشرح المبدأ نفسه لماذا يولّد المصدر كودًا مقروءًا لا كتلة مضغوطة. المطوّر الذي يستطيع
قراءة المُدقّق المولّد يستطيع أن يفهم القاعدة ويحكم عليها؛ والمطوّر الذي لا يستطيع يُطلب منه أن
يثق بالإطار.
هناك مقايضة هنا، وتستحق أن تُقال. التوليد وقت البناء يقيّد شكل النموذج. النماذج العامة المفتوحة
تُرفض بالتشخيص VAL0022؛ وواجهة fluent هي المخرج.
ويجب أن يعلن النموذج مساحة أسماء؛ والنموذج في مساحة الأسماء العامة غير مدعوم في هذا الإصدار.
هذه حدود حقيقية، لا حواشٍ. التصميم يختار الحتمية على قبول كل شكل قانوني في C#.
نموذج التنفيذ: حيث تتسرب عادةً أطر التحقق
معظم مكتبات التحقق تتعامل جيدًا مع المسار السعيد. تظهر الفروق عندما يحتاج النظام إلى الإجابة عن
أسئلة مثل:
- أي القواعد تعمل لهذه العملية؟
- هل نتوقف عند أول خطأ أم نجمع كل الأخطاء؟
- هل يوقف فشل عضو بقية النموذج؟
- هل يمكن لقاعدة أن تعتمد على نتيجة قاعدة أخرى؟
- هل تعمل القاعدة غير المتزامنة على المسار المتزامن؟
- ماذا يحدث عندما تلتقي قاعدة متداخلة ومجموعة ومجموعة قواعد؟
- هل يستطيع المستدعي اختيار مجموعة فرعية من القواعد دون إعادة بناء المُدقّق؟
يتعامل Jeninnet.Validation مع هذه الأسئلة كدلالات تنفيذ من الدرجة الأولى، لا كتفاصيل إعداد.
مجموعات القواعد تسمح للنداء باختيار مجموعة فرعية مسمّاة. وعندما يسمّي النداء مجموعات، لا تعمل
إلا تلك المجموعات؛ وإضافة default تُدخل القواعد غير المجمّعة. وعندما تكون
RuleSets فارغة أو null، تعمل كل القواعد، بما فيها
المجموعات المسمّاة. أسماء المجموعات غير حساسة لحالة الأحرف، والاستبعاد يتغلب على الإدراج. وتعرض
خيارات النداء ومُنشئ ValidationStrategy السلس الضوابط نفسها؛ وتضبط الخيارات
المحصورة بالحاوية محلّلات أسماء الخصائص وأسماء العرض، وبديل مصنع المُدقّقات، وأنماط التتابع
الافتراضية.
var result = validator.Validate(order, new ValidationCallOptions
{
RuleSets = ["strict"],
CascadeMode = CascadeMode.Stop,
FailFast = true
});
أنماط التتابع تحدد ما يحدث داخل العضو. النمط Continue يقيّم كل قاعدة؛
والنمط Stop يتخطى بقية قواعد العضو بعد أول فشل. التتابع على مستوى
الصنف يتوقف بعد أول عضو فاشل مع الحفاظ على سلوك العضو الداخلي. والتوقف عند أول خطأ
(FailFast) يتوقف عند أول خطأ في المسار كله.
الفرق بين التوقف عند أول خطأ والرمي عند الفشل مقصود. الأول يتحكم في الجمع. والثاني
(ThrowOnFailures) يتحكم في التسليم: تُجمع النتيجة، وتعمل خطافات الفشل، ثم
يحمل الاستثناء النهائي كل خطأ نجا من الجمع. الخلط بينهما مصدر شائع لسلوك مفاجئ في خطوط التحقق.
الشروط والقواعد التابعة تتحكم في التنفيذ دون أن يعيد كل مُدقّق كتابة شروط
if نفسها. ومرشحات الإدراج والاستبعاد والمحددات المخصصة تضيّق مجموعة
القواعد بعد عمل مجموعات القواعد ومرشحات الأعضاء. يبقى المسار الافتراضي بلا تخصيصات؛ ولا تُنشأ
مصفوفة قواعد جديدة إلا في المسارات المفلترة.
المجموعات والتداخل هي المكان الذي تضطرب فيه عادةً دلالات المسارات. يستخدم Jeninnet مسارات
بأقواس مثل Lines[0].Quantity، ويدعم قواعد عدد المجموعة،
وForEach مع مُدقّق فرعي، وForEachElement عندما يجب
التحقق من العناصر الفارغة، وWhere لتصفية قواعد المجموعة. ويُتاح
CollectionIndex كمعامل رسالة، ويغيّر
OverrideIndexer مقطع المسار المعروض. ويضيف
SetValidator بادئة المسار إلى أخطاء التداخل؛ وChildRules
هو المكافئ المضمّن؛ وSetInheritanceValidator يوزّع على النوع الفعلي بدقة.
عدم التزامن عقد، لا عرف. المُدقّق الذي يملك قواعد غير متزامنة ولا يملك قواعد متزامنة يرمي
AsyncValidatorInvokedSynchronouslyException على المسار المتزامن. لا يتخطى
القاعدة غير المتزامنة بصمت. هذا الاختيار أقل راحة على المدى القصير، وأصدق على المدى الطويل:
نتيجة تحقق تزعم النجاح لأن قاعدة تُخطّيت أسوأ من استثناء يسمّي المشكلة.
خطافات دورة الحياة جزء من نموذج القاعدة.
PreValidate/PreValidateAsync تستطيع إيقاف التقييم قبل
عمل القواعد؛ وOnFailure/OnFailureAsync تعمل بعد
الجمع. الخطافات التصريحية ثابتة ومتزامنة؛ والخطافات المكتوبة بـfluent تغطي
الحالات غير المتزامنة والمعتمدة على الخدمات. تُدمج أخطاء الخطاف مع أخطاء القواعد، لكن نتيجة
تحقق مسبق كاذبة توقف تقييم القواعد دائمًا.
التعقيم معالجة مسبقة صريحة. تقوم Sanitize و
[Sanitize] بالتشذيب وتوحيد الحالة وإزالة أحرف التحكم قبل عمل القواعد.
التعقيم يعدّل النموذج في مكانه، لذلك لا يكون صامتًا: عقد النموذج يقول إنه يحدث. يُدعم فقط
string وIList<string>، ولا توجد معالجات تعقيم
غير متزامنة، ويُرفض الواضع غير المتاح وقت البناء بالتشخيص VAL0027.
لا شيء من هذه الدلالات جديد بمعزل عن غيره. دعوى التصميم أنها تتركّب عبر محرك واحد، فيجيب
المُدقّق المولّد والمُدقّق المكتوب بـ fluent عن الأسئلة نفسها بالطريقة نفسها.
الواصف: كيف تنجو القاعدة من الرحلة
أكثر فكرة نافعة في الإطار ليست واجهة fluent ولا مولّد المصدر. إنها الواصف.
المُدقّقات المولّدة والمكتوبة بـ fluent تطبّق
IValidationDescriptorProvider. وتعيد Describe()
واصفًا مجمّدًا يحوي الأعضاء وأنواع القواعد ومفاتيح الرسائل والدرجات والشروط ومعاملات القواعد.
الواصف ليس سجلًا لما حدث. إنه وصف لما يعرفه المُدقّق. وتحمل أخطاء وقت التشغيل المفردات نفسها:
MemberName وMessageKey و
MessageParameters وErrorCode و
Severity وCustomState.
هذا الفرق هو ما يجعل جزء «الأسطح المتعددة» حقيقيًا. حزم JSON Schema (إصدار المسودة 2020-12،
حتمية وآمنة مع AOT) وOpenAPI وقواعد العميل تستهلك الواصفات. لا تنفذ التحقق. ولا تحتفظ بقائمة
موازية من القواعد. إنها تُسقط نموذج القواعد نفسه في صيغة مختلفة.
السمات وواجهة fluent يلتقيان عند محرك واحد؛ والمخططات وقواعد العميل إسقاطات للواصف نفسه.
using Jeninnet.Validation.JsonSchema;
using Jeninnet.Validation.ClientRules;
var descriptor = new CreateOrderValidator().Describe();
var jsonSchema = ValidationSchemaWriter.WriteToString(descriptor);
var clientRules = ClientRulesWriter.WriteToString([new CreateOrderValidator()]);
أمثلة قليلة تُظهر الإسقاط:
| القاعدة | الإسقاط إلى JSON Schema |
|---|---|
NotNull وNotEmpty
|
required؛ وNotEmpty يضيف minLength: 1 أو minItems: 1 عندما يكون النوع معروفًا |
Length(min, max) |
minLength / maxLength
|
EmailAddress() |
format: "email" |
InclusiveBetween(min, max) |
minimum / maximum
|
ForEach |
type: array وitems و$ref إلى مخطط العنصر |
Must وCustom والقواعد الشرطية |
إدخالات استشارية في x-validation-rules؛ والشروط تُعلّم بـhasCondition
|
الإسقاط صريح بشأن حدوده. required قيد حضور؛ لا يعبّر عن «ليس صفرًا» في
int. والقواعد الشرطية تُصدَّر استشاريًا لأن الدالة ليست تعبيرًا مخططًا قابلًا
للنقل. والقواعد المخصصة تبقى استشارية إلا إذا عرضت بيانات وصفية. ويبقى الخادم هو المرجع.
دعم OpenAPI مقسّم إلى ثلاثة محولات لأن فرق .NET لا تتفق على مولّد OpenAPI واحد:
Jeninnet.Validation.OpenApi لـ
Microsoft.AspNetCore.OpenApi، و
Jeninnet.Validation.OpenApi.Swashbuckle، و
Jeninnet.Validation.OpenApi.NSwag. وتقرأ المحولات الثلاثة السجل نفسه
ValidationSchemaRegistry، فتتطابق القيود مع مصدّرات JSON Schema وقواعد
العميل. وتحل أسماء الأعضاء عبر JsonSerializerOptions و
JsonTypeInfo النشطين، بما في ذلك [JsonPropertyName].
وتضيف المحولات الثلاثة فقط القيود التي يعلنها المُدقّق؛ ويحافظ محوّلا Swashbuckle وNSwag أيضًا على
نوع المخطط القائم.
تُصدَّر قواعد العميل بصيغة JSON أو TypeScript أو JavaScript. ويقيّم وقت التشغيل المرافق
@jeninnet/validation-client المجموعة المتزامنة المدعومة. وتُركّب القواعد
المتداخلة عندما يعرض المُدقّق الفرعي واصفًا. وعندما تكون القاعدة شرطية أو مخصصة أو غير متزامنة أو
غير قابلة للنقل، تُعلّم في الحمولة بـserverOnly: true، وتُعرض النتيجة
needsServer. هذا هو التصميم الصحيح: يحصل العميل على تغذية راجعة مبكرة، لا
على محرك مرجعي ثانٍ.
التكاملات: محولات، لا مركز
الإطار الذي يدّعي أنه مبني من وحدات يُقاس عادةً بمقدار ما يفرضه على المركز. يحافظ
Jeninnet.Validation على مركز صغير: العقود والمحرك. فكل تكامل مضيف هو حزمة منفصلة بعمر صريح ونمط
فشل صريح.
| السطح | الحزمة | ما تفعله |
|---|---|---|
| Minimal APIs وMVC | Jeninnet.Validation.AspNetCore |
مرشحات تحقق الطلبات، اعتراضات، ProblemDetails، معالجة استثناءات |
Microsoft.Extensions.Validation |
Jeninnet.Validation.Extensions.Validation |
IValidatableTypeInfo/IValidatableParameterInfo على .NET 11، وتحقق الخيارات |
| DataAnnotations | Jeninnet.Validation.DataAnnotations |
تشغيل المُدقّقات داخل خطوط DataAnnotations القائمة |
| Blazor | Jeninnet.Validation.Blazor |
محول EditContext، إرسال غير متزامن، وعرض data-val-* في SSR الثابت |
| سطح المكتب وMAUI وAvalonia | Jeninnet.Validation.Observable |
مزخرف INotifyDataErrorInfo لنماذج العرض |
| MediatR | Jeninnet.Validation.MediatR |
تحقق مجمّع للطلبات قبل المعالجات |
| نتائج MediatR |
Jeninnet.Validation.MediatR.ErrorOr و.FluentResults و.CSharpFunctionalExtensions
|
محولات نتائج اختيارية؛ يحافظ ErrorOr وFluentResults على بيانات التحقق، ويحافظ CSharpFunctionalExtensions على الرسالة |
| GraphQL | Jeninnet.Validation.GraphQL |
middleware لحقول HotChocolate لكائنات الإدخال |
| gRPC | Jeninnet.Validation.Grpc |
اعتراض للنداءات الأحادية وتدفق الخادم مع تفاصيل InvalidArgument وBadRequest
|
| التشخيص | Jeninnet.Validation.Diagnostics |
إشارات ActivitySource وMeter متوافقة مع OpenTelemetry |
حدود المحول ليست تجميلية. لا تشير الحزم الأساسية إلى ASP.NET Core أو MediatR أو Blazor أو GraphQL
أو gRPC. ومجموعة اختبارات البنية تثبّت ذلك. تطبيق console لا يدفع ثمن حزمة الويب. وتطبيق Blazor لا
يدفع ثمن محول Blazor إلا عندما يستخدمه.
أنماط الفشل صريحة أيضًا. ASP.NET Core وBlazor يتخطيان التحقق عندما لا يوجد مُدقّق مسجّل؛
وDataAnnotations يرمي عندما لا يستطيع إنشاء مُدقّق؛ ومحولات نتائج MediatR تأتي كحزم منفصلة لأن
خط المعالجة الأساسي لا يجب أن يعتمد على ErrorOr أو FluentResults أو CSharpFunctionalExtensions.
هذه قرارات صغيرة منفردة. ومجتمعة تُبقي رسم التبعيات مقروءًا.
التوطين ليس استبدال نصوص
معظم مكتبات التحقق تتعامل مع التوطين كبحث في قاموس. ينجح ذلك حتى تحتاج الرسالة إلى جمع، أو اختيار،
أو اسم عضو، أو قيمة حدّية، أو سلسلة ثقافات احتياطية لا تنتهي عند الإنجليزية.
تشحن Jeninnet.Validation.Localization حزم رسائل لأربعين ثقافة، وتغطي كل
ثابت في ValidationMessageKeys. ويدعم الخط رسائل ICU للجمع والاختيار،
والعناصر المسماة مثل {PropertyName} و{Min}
و{Max} و{CollectionIndex}
و{PropertyValue}، وأسماء ثقافات تحافظ على لاحقات الكتابة والمنطقة مثل
pt-BR وzh-Hans. وتضيف الحزمة الاختيارية
Jeninnet.Validation.Localization.AspNetCore جسر
IStringLocalizer/RESX بتحكم صريح في الثقافة وترتيب حل موثّق.
using Jeninnet.Localization.Abstractions.Options;
using Jeninnet.Validation.Localization;
services.AddSingleton(new LocalizationOptions { DefaultCulture = "en" });
services.AddDefaultMessagePacks();
using System.Globalization;
var localizer = provider.GetRequiredService();
foreach (var error in result.Errors)
{
var message = await localizer.LocalizeValidationErrorAsync(
error,
new CultureInfo("ar"));
}
يُبقي التصميم قاعدتين ظاهرتين. أولًا، تفرض المنصة وجود
IInnerMessageProvider واحد بالضبط؛ وإضافة مزوّد ثانٍ خطأ، لا لغز أسبقية
صامت. ثانيًا، الكتالوج وقت التشغيل محلي للعملية وفي الذاكرة. وإذا احتاج النظام رسائل دائمة أو
مشتركة بين نسخ، يسجّل ILocalizationStore ويستخدم منصة
Jeninnet.Localization الشقيقة، التي تدعم مصادر JSON وXML وRESX والذاكرة
وقواعد البيانات. هذا قرار نشر، ولا يجب أن يخفيه محرك التحقق.
حزم اللغات غير الإنجليزية المضمّنة مسودات بمساعدة آلية، وهي متتبعة صراحةً لمراجعة متحدث أصلي قبل
الإصدار المستقر. قول ذلك جزء من التصميم: ميزة توطين تشحن نصوصًا غير مراجعة دون مسار مراجعة هي
مسؤولية، لا ميزة.
لنموذج القاعدة دورة حياة
الإطار ليس فقط الكود الذي يعمل في الإنتاج. إنه أيضًا الاختبارات التي تصف القاعدة، والأدوات التي
تنقل الشيفرة القائمة إليه، والإشارات التي تخبر المشغّل إن كان يعمل.
حزمة Jeninnet.Validation.Assertions هي حزمة وقت الاختبار. تقدّم تأكيدات مثل
ShouldHaveValidationErrors().ForMember(...).ContainsRule(...)، فيستطيع
الاختبار أن يسمّي القاعدة التي يجب أن تفشل بدلًا من أن يؤكد على نص رسالة. وتعرض الحزمة نفسها مساعدات
TestValidate للمُدقّقات المولّدة والمكتوبة بـfluent.
هذه حزمة صغيرة بأثر كبير: تُبقي مجموعة الاختبارات مرتبطة بنموذج القاعدة، لا بعرض خطأ بعينه.
حزمة Jeninnet.Validation.Migration هي أداة التبني. تفحص مصادر C# بحثًا عن
أنماط FluentValidation وDataAnnotations، وتُبلغ عمّا يتحول نظيفًا، وتطبّق تحويلات آمنة وقابلة
للتكرار. وكل ما لا تفهمه يبقى دون تغيير مع علامة
// TODO(Jeninnet): صريحة وسطر في التقرير. ويتضمن التقرير درجة جاهزية الترحيل
والملفات القابلة للتحويل بالكامل. ويمكن تشغيله كبوابة في CI حتى لا يعود كود التحقق القديم خلسة.
dotnet tool install --global Jeninnet.Validation.Migration --version 1.0.0-preview.1
jeninnet migrate analyze ./src --format markdown --output migration-report.md
jeninnet migrate apply ./src --dry-run
jeninnet migrate apply ./src
وتضيف Jeninnet.Validation.Diagnostics إشارات
ActivitySource وMeter متوافقة مع OpenTelemetry لمدة
التحقق وعدد الأخطاء. لا تصل الرسائل ولا قيم الخصائص ولا الحالة المخصصة إلى الوسوم. وعندما لا يوجد
مُستقبِل إشارات مثبّت، لا يكلّف المحرك إلا فحصًا واحدًا للعدم؛ وعندما يوجد، يقرر المضيف ما يُعاين
وأين يُصدَّر. هذا هو الحد الصحيح: المراقبة شأن مضيف، لا سبب ليعرف محرك التحقق بائع القياسات.
وتضيف Jeninnet.Validation.Rules.Domain قواعد بنيوية اختيارية لـIBAN وأرقام
VAT والرموز البريدية والهويات الوطنية وقوة كلمات المرور وUUID وULID. وهي تعمل دون اتصال، وتعلن
الدول المدعومة صراحةً. تتحقق من الشكل ومجاميع التحقق؛ ولا تثبت وجود حساب أو شركة أو شخص.
الأداء وAOT: قيود على التصميم، لا شارة تسويقية
دعاوى الأداء سهلة القول وصعبة الإبقاء على صدقها. يقدّم Jeninnet.Validation ثلاث دعاوى محددة،
خلف كل واحدة اختبار أو قياس.
لا انعكاس على مسار التحقق. المُدقّقات المولّدة كود C# مجمّع. ومسار
fluent يستخدم وصولات مطبوعة. يوجد فحص تجميعات بالانعكاس، لكنه موسوم بـ
[RequiresUnreferencedCode] وله بديل تسجيل صريح. ويُنشر هيكل اختبار
NativeAOT ويشغّل المحرك والمولّد والتوطين وJSON المولّد في CI.
صفر تخصيصات على المسار الصالح. يُجمّع ValidationErrorCollector و
RootContextData لكل خيط. ويعيد اختيار القواعد المصفوفة الأصلية عندما لا
توجد مرشحات. وينسخ ValidationResult.FromErrors الأخطاء قبل إعادة المجمّع
إلى البركة. ويسجل التدقيق 0 B/op لـ5 و10 و30 خاصية يتم التحقق منها، و0 B/op لعمليات البحث في
التوطين وقاعدة Base64. مسارات الخطأ تخصّص الأخطاء نفسها، كما يجب: 968 بايت لخمسة أخطاء، و2,104
لعشرة، و6,024 لثلاثين. والتوقف عند أول خطأ يقلل الوقت والتخصيص معًا.
الأرقام اتجاهية، لا عالمية. على جهاز المستودع، قاس مقارنة الأقران 81.7 نانوثانية و0 بايت
لـJeninnet مقابل 226.7 نانوثانية و632 بايت لـFluentValidation على المسار الصالح. هذه الأرقام
مفيدة كخط أساس. وهي ليست وعدًا عن عتادك أو نموذجك أو معدل أخطائك. شغّل هيكل القياس قبل اتخاذ قرار
سعة.
ينطبق الانضباط نفسه على الصحة. تحتوي المجموعة على 997 اختبارًا على
net11.0. ويغطي تكافؤ القدرات 93/93 من اتحاد قدرات أقران .NET 10، و93/95 على
المصفوفة الكاملة؛ والسطران المتبقيان هما جسرا DataAnnotations غير المتزامن والخيارات غير المتزامنة
في .NET 11، المؤجّلان إلى 1.1.0-preview.1. ويشحن المستودع 26 مشروعًا من
العينات، بما فيها Clean Architecture وعينات توطين XML. وتُبلغ بوابة جودة SonarCloud عن تغطية
80.2%، و0.0% أسطر مكررة، و0 مشكلات مفتوحة؛ ومحللات AOT/trimming نظيفة.
ويعمل تحقق الحزم بـEnablePackageValidation=true. ويفحص فحص محتوى الحزمة
README والترخيص والأيقونة وتوثيق XML وتخطيط المحلل وأصول
lib/net11.0 المتوقعة. ويثبّت اختبار مستهلك الحزم المعبأة من مصدر محلي
ويتحقق من نموذج. وتُفحص دعاوى التوثيق مقابل المستودع. هذه ليست فحوصًا تسويقية. إنها الآلية التي
تمنع إطارًا من 25 حزمة من أن يصبح 25 مشروعًا غير مترابط.
خريطة القدرات
خريطة الحزم تجيب عن سؤال «ماذا أثبّت؟». وخريطة القدرات تجيب عن سؤال «ماذا يغطي الإصدار فعلًا؟».
كلتاهما مهمتان عندما يكون القرار معماريًا لا تكتيكيًا.
| الجانب | ما يقدّمه الإصدار |
|---|---|
| التأليف | السمات وتوليد المصدر، واجهة fluent، اختبارات تكافؤ تنفيذية، 33 تشخيصًا نشطًا من عائلة VAL، قواعد وقوالب مخصصة، وراثة، مجموعات وتداخل، تعقيم صريح |
| التنفيذ | مجموعات قواعد، أنماط تتابع، توقف عند أول خطأ، رمي عند الفشل، شروط، قواعد تابعة، مرشحات إدراج واستبعاد، محددات مخصصة، خطافات دورة حياة، عقد غير متزامن صارم، خيارات لكل نداء |
| البيانات الوصفية | واصفات مجمّدة؛ JSON Schema إصدار 2020-12؛ محولات OpenAPI لـMicrosoft.AspNetCore.OpenApi وSwashbuckle وNSwag؛ قواعد عميل بصيغة JSON وTypeScript وJavaScript |
| المضيفات | ASP.NET Core وMicrosoft.Extensions.Validation وDataAnnotations وBlazor وObservable UI وMediatR مع ثلاثة محولات نتائج وGraphQL وgRPC وتشخيص OpenTelemetry |
| التوطين | 40 ثقافة، جمع واختيار ICU، عناصر مسماة، جسر RESX، كتالوج وقت تشغيل، ومخازن متعددة المصادر عبر Jeninnet.Localization
|
| التشغيل | قواعد نطاق، تأكيدات اختبار، مساعد ترحيل، تحقق حزم، اختبار مستهلك، وهيكل اختبار NativeAOT |
| الضمان | 997 اختبارًا، تكافؤ 93/93 مع قدرات أقران .NET 10، مسار صالح بـ0 B/op، وفحوص دعاوى التوثيق |
خريطة الحزم الخمس والعشرين
حدود الحزمة قرار تصميمي، لا مفتاح ميزة. يشحن هذا الإصدار 25 حزمة لأن للإطار 25 سببًا مختلفًا
لاتخاذ تبعية.
| المجال | الحزم |
|---|---|
| النواة |
Jeninnet.Validation وJeninnet.Validation.Abstractions وJeninnet.Validation.Analyzers
|
| التوطين |
Jeninnet.Validation.Localization وJeninnet.Validation.Localization.AspNetCore
|
| الويب والواجهة |
Jeninnet.Validation.AspNetCore وJeninnet.Validation.Extensions.Validation وJeninnet.Validation.DataAnnotations وJeninnet.Validation.Blazor وJeninnet.Validation.Observable
|
| المراسلة |
Jeninnet.Validation.MediatR وJeninnet.Validation.MediatR.ErrorOr وJeninnet.Validation.MediatR.FluentResults وJeninnet.Validation.MediatR.CSharpFunctionalExtensions
|
| واجهات بعيدة |
Jeninnet.Validation.GraphQL وJeninnet.Validation.Grpc
|
| البيانات الوصفية والعملاء |
Jeninnet.Validation.JsonSchema وJeninnet.Validation.OpenApi وJeninnet.Validation.OpenApi.Swashbuckle وJeninnet.Validation.OpenApi.NSwag وJeninnet.Validation.ClientRules
|
| النطاق والتشغيل |
Jeninnet.Validation.Rules.Domain وJeninnet.Validation.Diagnostics وJeninnet.Validation.Assertions وJeninnet.Validation.Migration
|
مسار التبني مقصود أن يكون ضيقًا. ابدأ بـJeninnet.Validation و
Jeninnet.Validation.Analyzers. وأضف محول مضيف واحد عندما يحتاجه المضيف.
وأضف حزم البيانات الوصفية عندما ينشر النظام مخططًا أو عميلًا بالفعل. لا تتبنَّ الخريطة كلها في
اليوم الأول؛ خريطة الحزم قائمة اختيار، لا قائمة مهام.
ما لا يفعله هذا الإصدار
الإطار الذي يصف نقاط قوته فقط يطلب الثقة بدل أن يطلب التقييم. هذه هي الحدود التي يجب وزنها قبل
تبنّي الإصدار التجريبي.
-
net11.0فقط. كل مكتبة تُشحن تستهدفnet11.0؛ والمحلل يستهدفnetstandard2.0. وتشحن جسور DataAnnotations و Extensions.Validation أصولlib/net11.0. ويستخدم الحل C# 15. هذا إصدار يبدأ من .NET 11 STS، لا مسعى توافق متعدد الأهداف. -
تأجيل DataAnnotations غير المتزامن والخيارات غير المتزامنة. تُشحن الجسور المتزامنة الآن؛
والنسخ غير المتزامنة من .NET 11 مخططة لـ
1.1.0-preview.1. - بعض جسور الواجهة والأنظمة القديمة متزامنة. DataAnnotations ومسارات Blazor وObservable الافتراضية متزامنة؛ والقواعد غير المتزامنة وحدها ترمي على تلك المسارات. استخدم ASP.NET Core أو Minimal API أو MediatR أو مسار الإرسال غير المتزامن الصريح في Blazor للقواعد غير المتزامنة.
-
يجب أن يعلن النموذج مساحة أسماء. يولّد المولّد المُدقّقات تحت
<model namespace>.Validators؛ والنموذج في مساحة الأسماء العامة غير مدعوم في هذا الإصدار. -
القواعد المضمّنة مغلقة. الإغلاق يُبقي المسار الساخن قابلًا لإزالة الاستدعاء الافتراضي
(devirtualization) ويُبقي البيانات الوصفية صادقة. امتدّ عبر
Custom/CustomAsyncوRuleTemplateوSyncValidateRule/AsyncValidateRuleأو واجهات القواعد. - مخرجات المخطط والعميل إسقاطات. القواعد الشرطية والمخصصة وغير المتزامنة قد تُعلّم كخادم فقط؛ وتُركّب القواعد المتداخلة عندما يعرض المُدقّق الفرعي واصفًا. ويبقى الخادم هو المرجع.
- قواعد النطاق بنيوية. قواعد IBAN وVAT والرمز البريدي والهوية الوطنية تتحقق من الشكل ومجاميع التحقق؛ ولا تثبت وجود حساب أو شركة أو شخص.
- مسودات التوطين تحتاج مراجعة. حزم اللغات الأربعين مسودات بمساعدة آلية؛ ومراجعة المتحدث الأصلي متتبعة قبل الإصدار المستقر.
- هذا إصدار معاينة. السطح العام موثّق ومثبّت بخط أساس، لكن سياسة التوافق سياسة معاينة، لا ضمان إصدار مستقر.
لا شيء من هذه الحدود يُبطل التصميم. إنها تحدد النطاق الذي يمكن فيه تقييم التصميم.
جرّبه على حدود واحدة
أسرع طريقة لتقييم إطار تحقق ليست ترحيل حل كامل، بل اختيار حدّ واحد توجد فيه القاعدة مرتين، ثم حذف
نسخة واحدة.
dotnet add package Jeninnet.Validation --version 1.0.0-preview.1
dotnet add package Jeninnet.Validation.Analyzers --version 1.0.0-preview.1
using Jeninnet.Validation.Abstractions;
using Jeninnet.Validation.Catalog;
using Microsoft.Extensions.DependencyInjection;
using MyApp.Models;
var services = new ServiceCollection();
services.AddValidation();
using var provider = services.BuildServiceProvider();
var validator = provider.GetRequiredService>();
var result = validator.Validate(new Customer { Name = "", Email = "bad", Age = 10 });
foreach (var error in result.Errors)
{
Console.WriteLine($"{error.MemberName}: {error.Message ?? error.MessageKey}");
}
تجربة مركزة تبدو هكذا:
- أضف الحزمة الأساسية والمحلل إلى مشروع واحد.
- أضف السمات إلى نموذج واحد. نفّذ البناء واقرأ المُدقّق المولّد.
- تحقق من النموذج في نقطة نهاية واحدة أو معالج واحد. أبقِ الاختبارات القائمة.
- نادِ
Describe()وقارن مخرج JSON Schema أو قواعد العميل بالعقد الذي تنشره بالفعل. إذا اختلف المخرجان، فقد وجدت إما مهمة ترحيل أو تعارضًا حقيقيًا. - أضف حزمة تكامل واحدة فقط بعد نجاح الخطوات الأربع الأولى.
الترتيب مهم. البدء بحزم البيانات الوصفية يمنحك مخططًا بلا محرك تنفيذ. والبدء بمحول واجهة يمنحك
نموذجًا بلا عقد نطاق. والبدء بالنواة وحدّ واحد يمنحك دليلًا.
القاعدة يجب أن تنجو من الرحلة
السؤال المثير ليس هل تستطيع مكتبة تحقق أن تتحقق من نص. معظمها تستطيع. السؤال المثير هو هل تستطيع
قاعدة أن تنجو من الرحلة من النطاق إلى عقد الـ API، إلى العميل، إلى مجموعة الاختبارات، دون أن تصبح
قاعدة مختلفة.
هذه هي المشكلة التي صُمم هذا الإصدار ليجعلها مرئية. «قاعدة واحدة، محرك واحد، أسطح متعددة» ليست
شعارًا عن عدد الحزم. إنها قيد على المكان الذي يُسمح فيه لمعرفة التحقق أن تعيش.
إذا كان هذا القيد يطابق مشكلة تعرفها، فالإصدار جاهز لتجربة مركزة. وإذا كان نظامك متزامنًا بالكامل،
وذا سطح واحد، ومن غير المرجح أن ينشر مخططًا أو عميلًا، فقد تكون مكتبة أصغر الخيار الهندسي الأفضل.
الإطار مصمم ليجعل هذا الحكم أسهل، لا ليتخذه عنك.
إذا جرّبت الإصدار، فأكثر ما يفيدنا هو حالة حدودية: شكل نموذج، أو تركيب قواعد، أو تكامل مضيف لم
يناسب التصميم. افتح issue بأصغر مثال يمكن مشاركته.

Top comments (0)