أنماط Rust بعمق – الجزء 1: Newtypes في Rust
نظرة تقنية معمّقة على نمط Newtype في لغة البرمجة Rust. يتناول المقال كيف تختلف newtypes دلاليًا عن type aliases، وكيف يمكن للأغلفة ذات الحقول الخاصة فرض ثوابت المجال. ويغطي newtypes كمعالجات للموارد في بنى الرسوم البيانية، وتطبيق نمط typestate على التحقق من البيانات (مثل نوعي Email وFilter)، وطرق إخفاء تفاصيل التنفيذ للبقاء متوافقًا مع semver. كما يحذّر من المزالق النموذجية، مثل «التحويلات الخفية» أثناء التسلسل والكود المتكرر المفرط في بنى البيانات البسيطة.
لعل Newtypes أبسط نمط يُستخدم في لغة البرمجة Rust – بسيط إلى درجة أن تسميته نمطًا فيها شيء من المبالغة، ومع ذلك توجد مواقف بعينها يثبت فيها فائدة كبيرة. وفي الوقت نفسه، من السهل الإفراط في استخدامه، مما ينتج كودًا مطوّلًا أكثر من اللازم. فلنتعمق في هذا النمط ونفكر في أفضل موضع يناسبه.
ما هي newtypes؟
في جوهرها، الـ newtype هي بنية (structure) بحقل واحد تغلّف نوعًا أساسيًا:
struct Handler(usize);
هذا يعرّف newtype باسم Handler تخزّن داخلها usize. وهي حالة نموذجية جدًا بالنسبة لي: عندما يكون لدي متجه (vector) أساسي ولا أريد فهرسته بـ usize مجردة، أنشئ غلافًا Handler بدلًا من ذلك.
من الجدير بالذكر كيف تختلف newtypes عن type aliases. ما يلي ليس newtype:
type OtherHandler = usize;
OtherHandler ليست سوى اسم مستعار لـ usize. والفرق الحاسم أن newtype تُدخل فعلًا نوعًا جديدًا، بينما الكلمة المفتاحية type تعطي نوعًا موجودًا اسمًا آخر فحسب. ونتيجة لذلك، في هذا المثال يمكن تبادل OtherHandler وusize، بينما Handler نوع مختلف تمامًا:
fn takes_handler(handler: Handler) {}
fn takes_usize(handler: usize) {}
fn main() {
let raw = 0usize;
let handler = Handler(0);
// Note that I just assign an `usize` - its the exact same type
let other_handler = 0usize;
// Following would not compile, `Handler` is *not* an `usize`
// let handler2 = 0usize;
takes_usize(raw);
// `takes_usize` accepts `OtherHandler`
takes_usize(other_handler);
// But doesn't accept `Handler`
// takes_usize(handler);
// `takes_handler` accepts `Handler` only
takes_handler(handler);
// Passing `usize` or `OtherHandler` fails
// takes_handler(raw);
// takes_handler(other_handler);
}
بعد أن اتضح الفرق الشكلي بين type aliases وnewtypes، لننتقل إلى جانب آخر من واجهة API – إحكام إغلاق الحقل الداخلي. هل ينبغي أن يكون الحقل الوحيد في الـ newtype عامًا؟ من الناحية التقنية، أي الخيارين صحيح، لكنني شخصيًا أحجز اسم newtype للأنواع ذات الحقل الخاص. والسبب يكمن في الغرض من newtypes. فنحن نلجأ إلى هذا النمط عندما نحتاج تقنيًا إلى المعلومات التي يحملها نوع أساسي، لكننا نستخدمها بدلالات خاصة بالواجهة ولا نريد أن يُمرَّر النوع الأساسي مباشرة.
وبناءً على هذا المنطق – فبمجرد أن يصبح حقل الـ newtype عامًا، يستطيع مستخدم الواجهة الذي يملك النوع الأساسي أن يمرره مباشرة إلى الدالة، مما يُفرغ الغرض من newtypes من معناه إلى حد كبير. على سبيل المثال:
struct PubHandler(pub usize);
fn takes_pub_handler(handler: PubHandler) {}
fn main() {
let raw = 0usize;
let handler = PubHandler(0);
takes_pub_handler(handler);
// Passing `usize` fails
// takes_pub_handler(raw);
// But there is nothing stopping us to just create it in-place
take_pub_handler(PubHandler(raw));
}
يُدخل newtype كهذا قدرًا يسيرًا من الضجيج الصريح، وهو ما قد يكون بالضبط ما نريده، لكنه في رأيي يخدم في الغالب حالات استخدام مختلفة. لذلك أسمّي شخصيًا الأنواع ذات الحقول العامة أنواع غلاف (wrapper types) والأنواع ذات الحقول الخاصة newtypes. وهذا يتوافق أيضًا مع الاصطلاح الشائع الذي يتبع Rust by Example. وتذكّر أن هذا أقرب إلى إرشاد اصطلاحي – ففي منظومة Rust، قد ترى ما أسميه «أنواع الغلاف» يُشار إليه بـ «newtypes».
لماذا نستخدم newtypes؟
كما قلت سابقًا، أبسط استخدام لـ newtypes هو تمرير المعلومات التي يمثلها النوع الأساسي، لكن بدلالات مختلفة. ولأن المعنى مختلف، فعادةً لا نريد قبول أي قيمة من النوع الأساسي – بل نريد قدرًا من التحكم فيها.
أكثر حالتي استخدام شيوعًا هما:
- قبول القيم التي أنشأناها نحن في وقت سابق فقط.
- إرفاق تحقق بالقيمة.
وفي كثير من الأحيان نريد كليهما – أي أن القيم التي ترجعها واجهتنا صحيحة من البداية، وقد نظل نوفر طريقة لبناء الـ newtype من النوع الأساسي، مع تحقق إضافي.
حالة استخدام – newtype كمعالجات للموارد
أبسط مثال على newtype، وقد استخدمته عدة مرات، هو النوع Handler المعروض أعلاه. لنفترض أننا نبني مكتبة تحتفظ داخليًا برسم بياني (graph) – ربما رسم حوسبة. من أكثر طرق تمثيل الرسم البياني شيوعًا تخزين العقد في حاوية وإضافة وسيلة ما لتمثيل الاتصالات بينها – ربما في حاويات منفصلة.
مع هذا التمثيل، قد يكون GraphNode بنية مكلفة نوعًا ما نفضّل ألا نمررها. يمكننا استخدام Rc<GraphNode> بدلًا من ذلك، لكن الأسلوب البسيط في كثير من الأحيان هو الاحتفاظ بمتجه من العقد وتمرير فهرس العقدة بدلًا من العقدة كلها:
struct MyGraph {
nodes: Vec<GraphNode>,
}
impl MyGraph {
fn create_node(&mut self) -> usize {
nodes.push(GraphNode::default());
nodes.len() - 1
}
}
ثم، كلما أردنا فعل شيء بالعقد، نمرر فهارسها:
impl MyGraph {
fn add_connection(&mut self, from: usize, to: usize) {
self.nodes[from].add_connection(to)
}
}
يعمل هذا على نحو ممتاز، لكن العيب أن المستخدم يستطيع تغذية الواجهة بأرقام عشوائية، وقد يؤدي ذلك إلى مشكلات – وفي هذه الحالة على الأرجح إلى panic:
fn main() {
let mut graph = MyGraph::default();
let node1 = graph.create_node();
let node2 = graph.create_node();
// All is fine
graph.add_connection(node1, node2);
// Here we get a panic
graph.add_connection(100, 200);
}
قد لا يكون الأمر كارثيًا – فـ Rust ستضمن ألا يمكن الوصول إلى الفهارس غير الصالحة، ويمكن للتوثيق دائمًا أن ينص على أن الفهارس التي لم تُرجعها الطريقة create_node سابقًا يجب ألا تُمرَّر أبدًا.
ومع ذلك، يمكننا أن نفعل ما هو أفضل ونجعل إنشاء فهارس غير صالحة مستحيلًا:
struct NodeHandler(usize);
impl MyGraph {
fn create_node(&mut self) -> NodeHandler {
let index = self.nodes.len();
self.nodes.push(GraphNode::default());
NodeHandler(index)
}
fn add_connection(&mut self, from: NodeHandler, to: NodeHandler) {
self.nodes[from.0].add_connection(to.0)
}
}
الكود شبه مطابق لما سبق، لكنه يمنع بعض المشكلات. وقد يتساءل المرء: لماذا يمرر أحد قيمة لم نُرجعها قط؟ ربما افترض أنه يمكن تخزين القيم بأمان في قاعدة بيانات ثم استعادتها وإعادة استخدامها، وهذا غير صحيح. من غير المرجح أن يمرر أحد 100 مباشرة كفهرس عقدة، لكن إبطال قيمة حُصل عليها من شخص آخر خطأ محتمل إلى حد كبير.
كن حذرًا جدًا من أي افتراضات إضافية تضعها بشأن القيم التي تتلقاها. في هذا المثال، قد تفترض الطريقة add_connection أن المعاملين from وto عقدتان أنشأهما MyGraph، لكنها لا تستطيع أن تفترض بأمان أنهما من النسخة نفسها من MyGraph. تأمل المثال التالي:
impl MyGraph {
fn add_connection(&mut self, from: NodeHandler, to: NodeHandler) {
unsafe {
self.nodes.get_unchecked(from.0).add_connection(to.0)
}
}
}
من المغري التفكير بأننا، ما دمنا المنتج الوحيد لـ NodeHandler، نستطيع الوثوق به تمامًا وتطبيق التحسين الحاسم بتخطي فحص الحدود. غير أننا قد ننتهي بسهولة إلى كود غير سليم (unsound):
fn main() {
let graph1 = MyGraph::default();
let graph2 = MyGraph::default();
let node1 = graph1.create_node();
let node2 = graph2.create_node();
let node3 = graph3.create_node();
// `node3` index here is `1`, and the `self.nodes.get_unchecked(1)` becomes an unsound call
graph1.add_connection(node3, node2);
}
لو كان هذا التحسين مهمًا فعلًا، فيمكن تنفيذه، لكن ذلك سيتطلب أدوات إضافية مع lifetimes.
في سيناريو كهذا، عادةً ما تساعد Newtypes على تقديم واجهة API صديقة للمطوّر، لكنها نادرًا ما تساعد في تحسينات الأداء.
التحقق من الأنواع
ظهر الاستخدام الثاني لـ newtypes مؤخرًا في نادي الكتاب في شركتنا. في البداية كنت متشككًا بعض الشيء، لكنني أعتقد أن ذلك لأنه طُرح من زاوية ليست شائعة جدًا في Rust. ومع ذلك، هو تطبيق شائع جدًا لـ newtypes في لغة البرمجة Rust.
في المثال السابق، ضمنت newtypes أن معالج عقدة الرسم البياني أنشأته حزمتنا (crate) وليس مجرد قيمة usize عشوائية أُدخلت إلى نظامنا. وحالة أخرى لـ newtypes مشابهة – نريد تقييد القيم التي تُمرَّر إلى دالة، لكن لا يشترط أن تكون قيمًا أنشأناها سابقًا. ربما نريد فقط أن نتأكد من أن القيمة مرت بمعالجة معينة – وهذه المعالجة غالبًا ما تكون تحققًا.
وهذا مثال واقعي. لنفترض أننا نبني أداة شطرنج تصفّي المباريات. سيبدو كائن التصفية هكذا:
struct Filter {
pub player: Option<String>,
pub color: Option<Color>,
}
impl ChessService {
fn fetch_games(&self filter: Filter) -> Vec<Game> {
todo!()
}
}
تصف البنية Filter كيفية تصفية المباريات. في النسخة المبسطة، نريد فقط مباريات اللاعب المعطى. بالإضافة إلى ذلك، إذا حُدّد اللون، فنحصل فقط على المباريات التي لعبها هذا اللاعب بذلك اللون تحديدًا.
الافتراض الأساسي الذي نود الحفاظ عليه للبنية Filter سهل الرصد – ينبغي على الأرجح ألا يُضبط حقل اللون أبدًا عندما يكون player هو None. إحدى طرق التعامل مع ذلك هي التحقق من المرشّح داخل الطريقة fetch_games:
impl ChessService {
fn fetch_games(&self, filter: Filter) -> Vec<Game> {
if filter.player.is_none() && filter.color.is_some() {
panic!("Invalid filter: color cannot be set without player");
}
todo!()
}
}
يعمل هذا، لكن هناك مشكلة صغيرة – فإذا مُرّر المرشّح نفسه إلى fetch_games أو طرائق أخرى عدة مرات، فيجب التحقق منه في كل مرة. كلفة الأداء ليست كبيرة، لكنه عمل يمكن تجنبه بسهولة. ويحل نمط newtype هذه المشكلة:
struct ValidatedFilter(Filter);
impl ValidatedFilter {
fn new(filter: Filter) -> Self {
if filter.player.is_none() && filter.color.is_some() {
panic!("Invalid filter: color cannot be set without player");
}
Self(filter)
}
}
impl ChessService {
fn fetch_games(&self, filter: ValidatedFilter) -> Vec<Game> {
todo!()
}
}
الآن يحدث التحقق مرة واحدة فقط، عند إنشاء المرشّح، ويمكن لبقية النظام التعامل معه على أنه صالح. وعلى عكس الحالة السابقة، يمكننا هنا حتى كسب قدر من الأداء، لأن التحقق لا يعتمد على أي كيانات أخرى.
بالطبع، لا حاجة صارمة إلى newtype هنا – فيمكن للبنية ValidatedFilter أن تحتوي على كل حقول Filter، لكن ذلك يعني تكرار الكود.
يمكن اعتبار هذا الاستخدام لـ newtype تطبيقًا أساسيًا لنمط typestate. نمط typestate شائع في Rust؛ وفكرته استخدام نظام الأنواع للتعبير عن حالة كائن ما. هنا، النوع Filter مرشّح محتمل قد يكون لا يزال قيد الإنشاء، بينما النوع ValidatedFilter مرشّح في الحالة validated. وكثيرًا ما يُدمج هذا أيضًا مع البناة (builders) – إذ يعمل Filter كباني، ربما بطرائق لضبط الحقول، وتجري الطريقة الأخيرة Filter::build(self) التحقق وتعيد ValidatedFilter النهائي.
ومثال آخر على استخدام newtype للتحقق هو النوع Email في نظام نحتاج فيه إلى بريد إلكتروني صالح، وربما نريد أيضًا تصفية النطاقات المسموح بها أو تطبيق قوائم حظر. حتى التحقق الأساسي من البريد الإلكتروني معقد نوعًا ما، وفي بعض الأنظمة يمكن أن يصبح معقدًا بلا حدود.
ومع أن من الصعب تصور كيف سيؤثر أداء التحقق من البريد الإلكتروني في نظام يعتمد على صيغة البريد، يمكنني بسهولة تصور نظام يعتمد استقراره فعلًا على تلك الصيغة. وهذا ما تعلمته: إذا لم يتحقق المترجم من شيء ما، فسأنسى فعله عاجلًا أم آجلًا – أو سينساه أحد في فريقي. هكذا سيبدو الكود:
struct Email(String);
impl Email {
fn validate(str: String) -> Result<Self, ValidationError> {
// Validation code...
Self(str)
}
}
يساعد نمط newtype على ضمان ألا نتخطى التحقق من البريد الإلكتروني أبدًا – فالمتوقع من أي كود يعتمد على صيغة البريد الفعلية أن يستخدم الـ newtype دائمًا. أما الكود الذي يتعامل مع البريد كـ String أو &str فلا بأس به، ما دام ذلك الجزء من الكود لا يعتمد على الصيغة.
لاحظ أيضًا أنه في هذه الحالة قد يكون مفيدًا جدًا إضافة دوال للتحويل إلى سلسلة نصية – ربما تحويل From (لكن من Email إلى String فقط، وليس العكس أبدًا!)، وربما سمة AsRef أو حتى Deref تكشف السلسلة الداخلية. إن إعادة تحويل Email إلى String لا تسبب مشكلة – فحتى لو عُدّلت أو عولجت قبل أن تصل إلى الجزء الحرج من النظام، فسيتعين التحقق منها مجددًا لتصبح بريدًا إلكترونيًا صالحًا.
يمكننا الذهاب إلى أبعد من ذلك لجعل هذا الـ newtype أكثر ملاءمة. تتيح لنا السمة TryFrom تنفيذ التحويل من String إلى Email – وهو ليس تحويلًا مباشرًا غير مفحوص. ولأن التحويل قد يفشل، تتاح لنا فرصة التحقق:
impl TryFrom<String> for Email {
type Error = ValidationError;
fn try_from(value: String) -> Result<Self, Self::Error> {
Self::validate(value)
}
}
يمكننا إضافة مزيد من الدوال المساعدة والسماح بإلغاء التسلسل (deserializing) مباشرة إلى Email – فقط تذكّر أن تجري التحقق دائمًا عند ذلك. وعند استخدام serde لإلغاء التسلسل، ينبغي أن نكتب تنفيذًا مخصصًا لإلغاء التسلسل أو نستخدم السمة try_from الخاصة بـ serde.
إخفاء النوع الأساسي
هناك سبب آخر لاستخدام نمط newtype، وهو ذو قيمة خاصة عند بناء المكتبات – إخفاء النوع الأساسي كليًا. حتى الآن ركّزنا في الغالب على قيمة البيانات الأساسية وعاملنا الـ newtype أساسًا كحارس يُبقي المدخلات غير الصالحة خارج نظامنا.
لكننا قد نرغب أحيانًا في تجنب كشف النوع الأساسي من أجل الحفاظ على بعض المرونة لتغييرات الواجهة المستقبلية.
لنعد إلى مثال الرسم البياني. قلنا إن الرسم يتكون من قيم GraphNode محفوظة في متجه مخفي. لكننا قد نرغب في مرحلة ما في تغيير ذلك التنفيذ. ربما يختفي المتجه وننقل Rc<NodeData> بدلًا منه. أو ربما لن يكفي المتجه في مرحلة ما، وسنريد HashMap<Uuid, GraphNode> أو حتى قاعدة بيانات، حيث لن يكون usize نوع فهرس مناسبًا.
باستخدام نمط newtype في واجهة API للمكتبة، نمنح المستخدم نوعًا يعبّر عن دلالاته لا عن تفاصيل تنفيذه. وهذا يسهّل استبدال التنفيذ بأكمله دون رفع الإصدار الرئيسي (major version) مع البقاء متوافقين مع semver.
هل newtype هي الخيار الأول دائمًا؟
غطينا حالتين رئيسيتين يساعد فيهما نمط newtype على تقديم واجهة API أفضل. فالسؤال إذن – هل ينبغي أن نسعى إلى استخدام newtypes في كل موضع يبدو منطقيًا؟
أنا شخصيًا ضد ذلك. يمكن لـ newtypes تحسين الواجهة، لكنها بارعة بالقدر نفسه في إضافة الكود المتكرر.
وهذا مثال. لنفترض أننا نكتب مكتبة رسوميات ونريد تقديم نوع Color كالتالي:
struct Color(u8, u8, u8);
العناصر الثلاثة في Color هي قيم RGB، كل منها 8 بتات. لكننا شديدو الحماس لـ newtypes، فـ«نحسّن» واجهتنا:
struct Channel(u8);
struct Color(Channel, Channel, Channel);
impl Color {
fn new(r: Channel, g: Channel, b: Channel) -> Self {
Self(r, g, b)
}
}
المشكلة أننا في هذا الاستخدام تحديدًا نريد على الأرجح السماح ببناء Channel من u8 والعكس:
impl From<u8> for Channel {
fn from(value: u8) -> Self {
Self(value)
}
}
impl From<Channel> for u8 {
fn from(value: Channel) -> Self {
value.0
}
}
الآن يستطيع مستخدم حزمتنا فعلًا إنشاء لون أزرق:
fn main() {
let blue = Color(Channel::from(0), Channel::from(0), Channel::from(255));
}
ومع السمة Into، يمكن أن يبدو أجمل:
fn main() {
let blue = Color::new(0.into(), 0.into(), 255.into());
}
ومع ذلك لا أرى بصدق أي فائدة لهذه الصياغة مقارنة بـ Color::new(0, 0, 255) البسيطة. لقد أضفنا متطلب كود متكرر دون أن نكسب شيئًا ذا معنى.
قاعدتي العملية لاستخدام newtypes: استخدم واحدة إذا لم تكن ستوفر مُنشئًا يبني الـ newtype مباشرة من النوع الأساسي – سواء عبر طريقة أو عبر السمة From. فإذا كان الأمر كذلك، فهذا يعني وجود قيد ما على شكل القيمة، يُفحص كلما أُرجع النوع. لكن لاحظ أن مُنشئًا يجري تحققًا ليس ما أقصده بـالإنشاء المباشر. فإذا كان المُنشئ fn ValidatedFilter::new(Filter) -> Result<Filter>، فهي حالة مناسبة جدًا لنمط newtype.
مزلق شائع – التحويل الخفي
الفكرة التي أحاول إبقاءها حاضرة في هذا المقال كله هي أن الـ newtype ينبغي أن تضمن أن إنشاءها مضبوط. وثمة مزلق نموذجي واحد رأيته عدة مرات حين استُخدمت newtypes بإهمال – التحويل الخفي.
وكما ذكرت في مثال اللون، تؤدي newtypes أحيانًا إلى أكوام من استدعاءات from / into، وهو ما يشير بالنسبة لي إلى إساءة استخدام النمط.
ومع أن السمة From تحويل صريح جدًا، فعند تنفيذ newtypes ينبغي أن نكون حذرين بوجه خاص من أن كل مسار إنشاء – والتحويلات بخاصة – يمر عبر البناء السليم الذي يُبقي النوع متسقًا. والزلة المعتادة تتعلق بالتسلسل. وقد ذكرت هذا بالفعل في مثال Email، لكنه يستحق التكرار – لا تضع #[derive(Deserialize)] على newtypes الخاصة بك بلا تفكير. قد تكون serde::Deserialize، لكنها ستغطي كل نقطة إلغاء تسلسل قد تصادفها – تنفيذ بروتوكولك، ومخصّص الذاكرة الثنائي mmaping لديك.
ومثال مضاد ملموس جدًا لتطبيق newtypes يأتي من مشروع كنت أصونه – CosmWasm. فيه نوع واحد محدد واسع الاستخدام جدًا: Addr. Addr هي newtype فوق سلسلة نصية تمثل عنوان Cosmos صالحًا. وهي موثقة جيدًا وتُنشأ عبر التحقق، لكن بها عيبًا واحدًا – يمكن إلغاء تسلسلها مباشرة. وكانت هناك أسباب محددة جدًا لذلك، ولا أريد الخوض فيما إذا كان استثناءً مبررًا. وتعلقت الأسباب أساسًا بأن النوع يُسلسل ويُلغى تسلسله كثيرًا في التخزين؛ وبحكم طبيعة CosmWasm كان للأداء أهمية، وكذلك لتخطي التحقق عندما لا تكون هناك حاجة إليه.
لكن كانت هناك حالة واحدة تسبب فيها Deserialize بمشكلة حقيقية – إذ كان يمكن استخدام النوع Addr مباشرة كحقل في رسالة عقد ذكي واردة. وكانت لتلك الرسالة خاصية واحدة محددة – أنها تأتي من مستخدم غير موثوق. وهذه الزلة الصغيرة جعلت من الممكن تخطي التحقق من العنوان عن غير قصد، مما قد يؤدي إلى شتى أنواع الإخفاقات. لا أعرف أي أخطاء حرجة نتجت عنها، لكنني صادفت بعض المواقف التي أضعنا فيها وقتًا في الاختبار بسببها – مثل أخطاء الإعدادات التي كان يمكن اكتشافها مبكرًا بدلًا من أن تظهر كأخطاء عميقة.
عولجت المشكلة عبر إرشادات – فمطورو CosmWasm المخضرمون يعرفون ألا يضعوا Addr في أنواع الرسائل لهذا السبب تحديدًا. وفعلنا أمورًا مشابهة مع الأرقام في الماضي – فمثلًا، أجبرتنا قيود تنفيذ Wasm على تجنب i128.
إنه مجرد مثال واقعي واحد، لكنه علّمني درسًا قيّمًا حول العمل مع newtypes.
الكلمة الأخيرة
النقطة الجوهرية في نمط newtype هي التحكم في كيفية إنشاء النوع، أيًّا كان السبب. استخدمه كلما منحك شروطًا مسبقة مفيدة يفحصها نظام الأنواع – واستخدمه بعناية! تذكّر دائمًا مراجعة كل مسار إنشاء، واستمتع بقاعدة كود نظيفة على طريقة Rust.