كتالوج البرمجيات ونموذج الكيانات

كتالوج البرمجيات هو الميزة الأساسية لـ Backstage—سجل مركزي لجميع أصولك البرمجية. فهم نموذج الكيانات ضروري لبناء بوابة مطورين فعالة.

نموذج الكيانات

يستخدم Backstage نموذج كيانات محدد جيداً يعتمد على واصفات YAML:

┌─────────────────────────────────────────────────────────┐
│                    تسلسل الكيانات                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Domain (قدرة العمل)                                    │
│    └── System (مجموعة من المكونات)                      │
│          ├── Component (خدمة، موقع، مكتبة)              │
│          │     └── API (واجهات مقدمة)                   │
│          └── Resource (قواعد بيانات، طوابير)            │
│                                                         │
│  Group (الفريق)                                         │
│    └── User (الشخص)                                     │
│                                                         │
└─────────────────────────────────────────────────────────┘

أنواع الكيانات

كل نوع كيان يخدم غرضاً محدداً:

النوع	الغرض	المثال
Component	قطعة برمجية	خدمة المستخدم، تطبيق React
API	تعريف الواجهة	REST API، مخطط GraphQL
Resource	البنية التحتية	PostgreSQL، حاوية S3
System	مجموعة	نظام إدارة الطلبات
Domain	مجال العمل	المدفوعات، الشحن
Group	الفريق	فريق المنصة، فريق الخلفية
User	الفرد	john.doe@acme.com

catalog-info.yaml للمكونات

كل كيان متتبع يحتاج ملف catalog-info.yaml:

# catalog-info.yaml - Component (خدمة)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: يتعامل مع مصادقة المستخدم وإدارة الملف الشخصي
  title: خدمة المستخدم
  annotations:
    # تكامل GitHub
    github.com/project-slug: acme/user-service
    # حالة CI/CD
    github.com/workflows: build,test,deploy
    # المراقبة
    prometheus.io/scrape: 'true'
    grafana/dashboard-url: https://grafana.acme.com/d/user-service
    # المناوبة
    pagerduty.com/service-id: P123ABC
    # التوثيق
    backstage.io/techdocs-ref: dir:.
  tags:
    - nodejs
    - typescript
    - api
  links:
    - url: https://user-service.acme.com
      title: رابط الإنتاج
    - url: https://grafana.acme.com/d/user-service
      title: لوحة Grafana
spec:
  type: service
  lifecycle: production
  owner: team-backend
  system: user-management
  providesApis:
    - user-api
  consumesApis:
    - notification-api
  dependsOn:
    - resource:user-database
    - component:auth-library

catalog-info.yaml لـ APIs

حدد APIs بشكل منفصل لقابلية اكتشاف أفضل:

# catalog-info.yaml - API
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: user-api
  description: REST API لعمليات المستخدم
  tags:
    - rest
    - users
spec:
  type: openapi
  lifecycle: production
  owner: team-backend
  system: user-management
  definition: |
    openapi: 3.0.0
    info:
      title: User API
      version: 1.0.0
    paths:
      /users:
        get:
          summary: قائمة المستخدمين
          responses:
            '200':
              description: قائمة المستخدمين
      /users/{id}:
        get:
          summary: الحصول على مستخدم بالمعرف
          parameters:
            - name: id
              in: path
              required: true
              schema:
                type: string
          responses:
            '200':
              description: تفاصيل المستخدم

catalog-info.yaml للموارد

تتبع موارد البنية التحتية:

# catalog-info.yaml - Resource (قاعدة بيانات)
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: user-database
  description: قاعدة بيانات PostgreSQL لبيانات المستخدم
  annotations:
    # رابط لوحدة تحكم السحابة
    aws.amazon.com/rds-instance: user-db-prod
  tags:
    - postgresql
    - rds
spec:
  type: database
  owner: team-backend
  system: user-management
  dependencyOf:
    - component:user-service

catalog-info.yaml للأنظمة

جمّع المكونات ذات الصلة:

# catalog-info.yaml - System
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: user-management
  description: |
    نظام إدارة المستخدم يتعامل مع جميع جوانب هوية
    المستخدم والمصادقة وإدارة الملف الشخصي.
  tags:
    - core
    - auth
spec:
  owner: team-backend
  domain: identity

علاقات الكيانات

تتصل الكيانات من خلال العلاقات:

# أنواع العلاقات في Backstage
relationships:

  ownership:
    field: "spec.owner"
    example: "owner: team-backend"
    description: "أي فريق يملك هذا الكيان"

  system_membership:
    field: "spec.system"
    example: "system: user-management"
    description: "أي نظام ينتمي إليه"

  api_provision:
    field: "spec.providesApis"
    example: "providesApis: [user-api]"
    description: "APIs التي يكشفها هذا المكون"

  api_consumption:
    field: "spec.consumesApis"
    example: "consumesApis: [notification-api]"
    description: "APIs التي يستدعيها هذا المكون"

  dependencies:
    field: "spec.dependsOn"
    example: "dependsOn: [resource:user-database]"
    description: "التبعيات الصلبة"

ملفات كيانات متعددة

يمكنك تحديد كيانات متعددة في ملف واحد:

# catalog-info.yaml - كيانات متعددة
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
spec:
  type: service
  owner: team-orders
  system: order-management
  providesApis:
    - order-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
spec:
  type: openapi
  owner: team-orders
  system: order-management
  definition:
    $text: ./openapi.yaml
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: order-database
spec:
  type: database
  owner: team-orders
  system: order-management

اكتشاف الكتالوج

كوّن كيف يكتشف Backstage الكيانات:

# app-config.yaml - مواقع الكتالوج
catalog:
  rules:
    - allow: [Component, API, Resource, System, Domain, Group, User]

  locations:
    # مؤسسة GitHub - اكتشاف تلقائي لجميع المستودعات
    - type: github-discovery
      target: https://github.com/acme-corp/*/blob/main/catalog-info.yaml

    # مستودعات محددة
    - type: url
      target: https://github.com/acme/user-service/blob/main/catalog-info.yaml

    # ملف ثابت للفرق/المجموعات
    - type: file
      target: ./org-data/teams.yaml

    # تكامل AWS
    - type: aws-s3-discovery
      target: https://acme-catalog.s3.us-east-1.amazonaws.com/

في الدرس التالي، سنستكشف قوالب البرمجيات لأتمتة إنشاء المشاريع. :::