ADR-002 - ฐานข้อมูลที่เป็นนามธรรม

ADR-002: นามธรรมของฐานข้อมูล

บันทึกการตัดสินใจทางสถาปัตยกรรมสำหรับรูปแบบการเข้าถึงฐานข้อมูลเชิงวัตถุของ XOOPS

---

สถานะ

ยอมรับ - รูปแบบหลักตั้งแต่ XOOPS 2.0

---

บริบท

XOOPS ต้องการกลยุทธ์การโต้ตอบกับฐานข้อมูลที่จะ:

1. ไวยากรณ์ SQL เฉพาะฐานข้อมูลที่เป็นนามธรรม
2. ให้การดำเนินการ CRUD ที่สอดคล้องกันในทุกโมดูล
3. เปิดใช้งานการฆ่าเชื้อข้อมูลอัตโนมัติและการหลบหนี
4. รองรับการเปลี่ยนแปลงกลไกฐานข้อมูลในอนาคต
5. ลดความซับซ้อนของการดำเนินการทั่วไปสำหรับนักพัฒนา

ทางเลือกอื่นคือ:

• Raw SQL ตลอดทั้งโค้ดเบส
• เต็ม ORM (หลักคำสอน ฝีปาก)
• นามธรรมน้ำหนักเบาที่กำหนดเอง

---

แผนภาพการตัดสินใจ

mermaid
graph TB
    subgraph "Application Layer"
        A[Module Code]
        B[Handler Methods]
    end

    subgraph "Abstraction Layer"
        C[XoopsObjectHandler]
        D[XoopsPersistableObjectHandler]
        E[Criteria System]
    end

    subgraph "Database Layer"
        F[XoopsDatabase]
        G[MySQLDatabase]
        H[PDO Wrapper]
    end

    subgraph "Storage"
        I[(MySQL/MariaDB)]
    end

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    E --> F
    F --> G
    F --> H
    G --> I
    H --> I

---

การตัดสินใจ

เราจะใช้ Handler Pattern กับ:

1. XoopsObject - ที่เก็บข้อมูล

แต่ละเอนทิตีข้อมูลขยาย XoopsObject:

class Item extends XoopsObject
{
    public function __construct()
    {
        $this->initVar('id', XOBJ_DTYPE_INT, null, false);
        $this->initVar('title', XOBJ_DTYPE_TXTBOX, '', true, 255);
        $this->initVar('content', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('status', XOBJ_DTYPE_INT, 0, false);
    }
}

2. ตัวจัดการ - ผู้จัดการฝ่ายปฏิบัติการ

แต่ละวัตถุมีตัวจัดการที่สอดคล้องกัน:

class ItemHandler extends XoopsPersistableObjectHandler
{
    public function __construct($db)
    {
        parent::__construct($db, 'mymodule_items', Item::class, 'id', 'title');
    }

    // CRUD methods inherited:
    // - create(), get(), insert(), delete()
    // - getObjects(), getCount(), getAll()
}

3. เกณฑ์ - ตัวสร้างแบบสอบถาม

เงื่อนไขการสืบค้นเชิงวัตถุ:

$criteria = new CriteriaCompo();
$criteria->add(new Criteria('status', 1));
$criteria->add(new Criteria('created', time() - 86400, '>='));
$criteria->setSort('created');
$criteria->setOrder('DESC');
$criteria->setLimit(10);

$items = $handler->getObjects($criteria);

---

ค่าคงที่ประเภทข้อมูล

// Variable types with automatic sanitization
XOBJ_DTYPE_INT       // Integer
XOBJ_DTYPE_TXTBOX    // Single-line text (escaped)
XOBJ_DTYPE_TXTAREA   // Multi-line text (escaped)
XOBJ_DTYPE_EMAIL     // Email validation
XOBJ_DTYPE_URL       // URL validation
XOBJ_DTYPE_ARRAY     // Serialized array
XOBJ_DTYPE_OTHER     // No processing
XOBJ_DTYPE_FLOAT     // Floating point

---

มรดกตัวจัดการ

mermaid
classDiagram
    class XoopsObjectHandler {
        <<abstract>>
        #db: XoopsDatabase
        +create(): XoopsObject
        +get(id): XoopsObject
        +insert(object): bool
        +delete(object): bool
    }

    class XoopsPersistableObjectHandler {
        +getObjects(criteria): array
        +getCount(criteria): int
        +getAll(criteria): array
        +deleteAll(criteria): bool
        +updateAll(field, value, criteria): bool
    }

    class ItemHandler {
        +getPublishedItems(): array
        +getByCategory(catId): array
    }

    XoopsObjectHandler <|-- XoopsPersistableObjectHandler
    XoopsPersistableObjectHandler <|-- ItemHandler

---

ผลที่ตามมา

คิดบวก

1. ความสม่ำเสมอ: โมดูลทั้งหมดใช้รูปแบบเดียวกัน
2. ความปลอดภัย: การหลบหนีอัตโนมัติป้องกันการฉีด SQL
3. ความเรียบง่าย: การดำเนินการทั่วไปต้องใช้โค้ดน้อยที่สุด
4. การบำรุงรักษา: การเปลี่ยนแปลงเลเยอร์ฐานข้อมูลไม่มีผลกับโมดูล
5. ความสามารถในการทดสอบ: สามารถจำลองตัวจัดการเพื่อทำการทดสอบได้

เชิงลบ

1. ประสิทธิภาพ: โอเวอร์เฮดที่เป็นนามธรรมเพิ่มเติม
2. ความซับซ้อน: เส้นโค้งการเรียนรู้สำหรับนักพัฒนาใหม่
3. ข้อจำกัด: การสืบค้นที่ซับซ้อนอาจต้องใช้ข้อมูลดิบ SQL
4. ปัญหา N+1: ไม่มีการโหลดแบบกระตือรือร้นในตัว

การบรรเทาผลกระทบ

• ประสิทธิภาพ: แคชวัตถุที่เข้าถึงบ่อย
• ข้อความค้นหาที่ซับซ้อน: อนุญาตข้อมูลดิบ SQL เมื่อจำเป็น
• N+1: ใช้ getAll() ด้วยเกณฑ์ที่เหมาะสม

---

วิวัฒนาการเป็น XOOPS 4.0

mermaid
flowchart LR
    subgraph "Current (2.5.x)"
        A[XoopsDatabase]
        B[Handlers]
        C[Criteria]
    end

    subgraph "Future (4.0.x)"
        D[PDO/DBAL]
        E[Repository Pattern]
        F[Query Builder]
        G[DI Container]
    end

    A --> D
    B --> E
    C --> F
    D --> G
    E --> G

XOOPS แผน 4.0:

• หลักคำสอน DBAL สำหรับนามธรรมฐานข้อมูล
• รูปแบบพื้นที่เก็บข้อมูลแทนที่ตัวจัดการ
• ตัวสร้างแบบสอบถามสำหรับการสืบค้นที่ซับซ้อน
• การรวมคอนเทนเนอร์ PSR-11 เต็มรูปแบบ

---

ตัวอย่างโค้ด

พื้นฐาน CRUD

$helper = Helper::getInstance();
$handler = $helper->getHandler('Item');

// Create
$item = $handler->create();
$item->setVar('title', 'New Item');
$handler->insert($item);

// Read
$item = $handler->get($id);
$title = $item->getVar('title');

// Update
$item->setVar('title', 'Updated Title');
$handler->insert($item);

// Delete
$handler->delete($item);

แบบสอบถามที่ซับซ้อน

$criteria = new CriteriaCompo();
$criteria->add(new Criteria('status', 'published'));
$criteria->add(new Criteria('category_id', '(1,2,3)', 'IN'));
$criteria->add(new Criteria('created', strtotime('-30 days'), '>='));
$criteria->setSort('views');
$criteria->setOrder('DESC');
$criteria->setLimit(10);
$criteria->setStart(0);

$items = $handler->getObjects($criteria);
$total = $handler->getCount($criteria);

---

การตัดสินใจที่เกี่ยวข้อง

• ADR-001: สถาปัตยกรรมแบบโมดูลาร์
• ADR-003: เครื่องมือเทมเพลต Smarty

---

อ้างอิง

• Martin Fowler - รูปแบบของสถาปัตยกรรมแอปพลิเคชันระดับองค์กร
• แนวคิดการออกแบบที่ขับเคลื่อนด้วยโดเมน
• รูปแบบ Active Record และ Data Mapper

---

#xoops #architecture #adr #database #handler #การออกแบบ-การตัดสินใจ