萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

HTML5 離線儲存實戰:Web SQL Database CRUD 完整封裝與應用架構

背景與現狀

Web SQL Database 規範已停止維護(主因:實現者高度同質化,幾乎皆採用 SQLite)。但理解其操作模式有助於掌握 HTML5 客戶端儲存演進脈絡。現代專案建議改用 IndexedDB 或封裝庫(如 localForage、Dexie.js、RxDB)。

核心架構:資料庫操作封裝類

// 資料庫操作核心類
const dataBaseOperator = {
    // 開啟資料庫連線
    openDatabase() {
        return openDatabase(
            'dataBaseUserStories',   // 資料庫名稱
            '1.0',                   // 版本
            'User stories database', // 描述
            2 * 1024 * 1024          // 大小 2MB
        );
    },

    // 通用 SQL 執行方法(增刪改查皆適用)
    execute(sql, params = []) {
        return new Promise((resolve, reject) => {
            const db = this.openDatabase();
            db.transaction(tx => {
                tx.executeSql(sql, params,
                    (_, result) => resolve(result),
                    (_, error) => { reject(error); return true; } // 返回 true 表示已處理錯誤
                );
            });
        });
    }
};

// 便利別名
dataBaseOperator.executeNonQuery = dataBaseOperator.execute;
dataBaseOperator.executeReader = dataBaseOperator.execute;
dataBaseOperator.executeScalar = dataBaseOperator.execute;

業務邏輯層:UserStory Provider

class UserStoryProvider {
    constructor() {
        this.tableName = 'tbUserStories';
    }

    // 建立資料表
    async createTable() {
        const sql = `CREATE TABLE IF NOT EXISTS ${this.tableName} (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            role TEXT, ability TEXT, benefit TEXT,
            name TEXT, importance TEXT, estimate TEXT, notes TEXT
        )`;
        await dataBaseOperator.execute(sql);
    }

    // 刪除資料表
    async dropTable() {
        await dataBaseOperator.execute(`DROP TABLE IF EXISTS ${this.tableName}`);
    }

    // 新增故事
    async add(story) {
        const sql = `INSERT INTO ${this.tableName} 
            (role, ability, benefit, name, importance, estimate, notes)
            VALUES (?, ?, ?, ?, ?, ?, ?)`;
        const params = [
            story.role, story.ability, story.benefit,
            story.name, story.importance, story.estimate, story.notes
        ];
        return dataBaseOperator.execute(sql, params);
    }

    // 刪除故事
    async remove(id) {
        return dataBaseOperator.execute(
            `DELETE FROM ${this.tableName} WHERE id = ?`, [id]
        );
    }

    // 讀取所有故事
    async loadAll() {
        const result = await dataBaseOperator.execute(
            `SELECT * FROM ${this.tableName}`, []
        );
        return Array.from(result.rows).map(row => new UserStory(
            row.id, row.name, row.role, row.ability,
            row.benefit, row.importance, row.estimate, row.notes
        ));
    }
}

// 領域模型
class UserStory {
    constructor(id, name, role, ability, benefit, importance, estimate, notes) {
        Object.assign(this, { id, name, role, ability, benefit, importance, estimate, notes });
    }
}

前端整合應用範例

// 初始化
const provider = new UserStoryProvider();
await provider.createTable();

// UI 綁定範例(配合 jQuery)
$('#btnAdd').on('click', async () => {
    const item = {
        role: $('#role').val(),
        ability: $('#ability').val(),
        benefit: $('#benefit').val(),
        name: $('#name').val(),
        importance: $('#importance').val(),
        estimate: $('#estimate').val(),
        notes: $('#notes').val()
    };
    try {
        await provider.add(item);
        await renderList();
    } catch (e) { alert('新增失敗:' + e.message); }
});

async function renderList() {
    const stories = await provider.loadAll();
    $('#list').html(stories.map(s => 
        `
  • ${s.name} (${s.role}) - ${s.estimate}pts
  • ` ).join('')); } // 頁面載入時渲染 $(document).ready(renderList);

    關鍵技術細節

    1. 非同步交易模型

    Web SQL 採用非同步回調/Promise 模式,所有 DB 操作不阻塞 UI 執行緒。

    2. 參數化查詢防 SQL 注入

    使用 ? 佔位符 + 參數陣列,絕不直接字串拼接 SQL。

    3. 結果集處理

    • result.rows.length:筆數
    • result.rows.item(i):取得第 i 筆物件
    • result.insertId:自增主鍵值
    • result.rowsAffected:影響列數

    4. 版本管理與遷移

    // 開啟時指定版本,配合 changeVersion 進行結構遷移
    const db = openDatabase('myDB', '2.0', 'desc', 5*1024*1024);
    db.changeVersion('1.0', '2.0', tx => {
        tx.executeSql('ALTER TABLE users ADD COLUMN email TEXT');
    });

    現代替代方案對比

    方案優點缺點適用場景
    IndexedDB標準、大容量、索引查詢、事務支援API 複雜、學習曲線陡大型離線應用、複雜查詢需求
    localStorageAPI 簡單、同步、廣泛支援5MB 限制、同步阻塞、僅字串簡單鍵值對、設定檔、Token
    localForage統一 API、自動降級、Promise 風格需引入庫、間接層效能損耗快速開發、跨瀏覽器相容
    Dexie.jsIndexedDB 友善封裝、TypeScript 支援僅封裝 IndexedDB需 IndexedDB 功能但怕複雜
    RxDB即時同步、加密、Schema 驗證、Observable體積較大、學習成本高協同應用、P2P 同步、複雜狀態

    遷移建議

    1. 新專案直接採用 IndexedDB + 封裝庫
    2. 舊專案漸進式遷移:新功能用新方案,舊資料保留 Web SQL 至自然淘汰
    3. 建立抽象儲存介面,業務邏輯不直接依賴具體實現
    4. 注意 Safari 私密模式下 IndexedDB/localStorage 會拋錯,需 try-catch 降級
    copyright © 萬盛學電腦網 all rights reserved