Hasura 入門指南：快速打造高效 GraphQL API

更新日期： 2025 年 3 月 18 日

在現代應用開發中，GraphQL 以其靈活查詢、減少不必要的數據傳輸以及強大的開發體驗，逐漸成為取代傳統 REST API 的熱門選擇。

然而，手動撰寫 GraphQL 伺服器可能會帶來額外的開發與維護成本，因此 Hasura 應運而生。

Hasura 是一款開源的 GraphQL 引擎，能夠自動將 PostgreSQL 資料庫轉換為 GraphQL API，幫助開發者在短時間內建立高效能的後端服務。

本文將帶你認識 Hasura 的核心概念、安裝方式，以及如何透過 Hasura 快速開發 GraphQL API。

一般後端 GraphQL API 的開發流程

從零開始開發一個 GraphQL API，通常會經歷以下步驟：

設計 GraphQL Schema

GraphQL 需要定義 Schema 來描述 API 的數據結構，包括：

• Type 定義：定義資料結構，例如 User、Post 等。
• Query：查詢數據的 API，如 getUser(id: ID!): User。
• Mutation：修改數據的 API，如 createUser(name: String!): User。
• Subscription：即時訂閱 API，如 onUserUpdated(id: ID!): User。

💡 範例 Schema

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  getUser(id: ID!): User
}

type Mutation {
  createUser(name: String!, email: String!): User
}

設計並建置資料庫

• 選擇資料庫（如 PostgreSQL、MySQL、MongoDB）。
• 設計表格結構（Tables）、索引（Indexes）、關聯（Relations）。
• 撰寫 Migration 檔案來維護數據結構變更。

💡 SQL 建立 users 表格

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL
);

建立 GraphQL 伺服器

• 使用框架（如 Apollo Server、Express + graphql-yoga、NestJS）搭建 GraphQL 伺服器。
• 設定 HTTP 伺服器，讓前端能夠透過 /graphql 端點請求數據。

💡 Node.js + Express + Apollo Server 範例

const { ApolloServer, gql } = require('apollo-server-express');
const express = require('express');

const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }
  type Query {
    getUser(id: ID!): User
  }
`;

const resolvers = {
  Query: {
    getUser: async (_, { id }) => {
      return db.users.find(user => user.id === id);
    },
  },
};

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });

server.applyMiddleware({ app });

app.listen(4000, () => console.log('Server running on http://localhost:4000/graphql'));

撰寫 Resolvers（解析函式）

Resolvers 是 GraphQL API 的核心，負責處理查詢、變更請求並與資料庫互動。

• Query Resolvers：處理讀取數據的請求。
• Mutation Resolvers：處理寫入、更新、刪除數據的請求。
• Subscription Resolvers：處理即時數據訂閱請求。

💡 範例 Resolvers（Node.js + Prisma）

const resolvers = {
  Query: {
    getUser: async (_, { id }, { db }) => {
      return db.user.findUnique({ where: { id } });
    },
  },
  Mutation: {
    createUser: async (_, { name, email }, { db }) => {
      return db.user.create({ data: { name, email } });
    },
  },
};

設定身份驗證與存取控制（Auth & Authorization）

• 身份驗證（Authentication）：確保請求來自合法使用者（如 JWT、OAuth）。
• 存取權限（Authorization）：不同角色可存取不同數據（如 RBAC、ABAC）。

💡 Middleware 驗證 JWT Token（Express + JWT）

const jwt = require('jsonwebtoken');

const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ message: 'Unauthorized' });

  try {
    const decoded = jwt.verify(token, 'your_secret_key');
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ message: 'Invalid token' });
  }
};

部署 API 到伺服器

• 選擇雲端服務（如 AWS、Heroku、Vercel）。
• 設定 Docker、CI/CD 來自動化部署。

Hasura 可以幫我省略哪些步驟？

Hasura 自動化了許多 GraphQL API 的開發流程，讓你無需手動撰寫後端程式碼，即可獲得完整的 GraphQL API。

省略 Schema 設計與 Resolvers 撰寫

• Hasura 會根據資料庫表格結構，自動生成 GraphQL Schema。
• 內建 Query、Mutation、Subscription，無需手寫 Resolvers。

💡 在 Hasura 中，建立 users 表後，API 會自動生成

query {
  users {
    id
    name
    email
  }
}

mutation {
  insert_users(objects: { name: "Alice", email: "[email protected]" }) {
    returning {
      id
    }
  }
}

省略後端開發與 API 伺服器建置

• 無需搭建 Apollo Server、Express 等後端框架。
• Hasura 直接提供 GraphQL API，可透過 http://localhost:8080/v1/graphql 存取。

內建身份驗證與存取權限管理

• 透過 JWT 進行身份驗證，無需手寫 Middleware。
• 內建 Role-Based Access Control（RBAC），可視覺化設定不同角色的存取權限。

💡 設定 user 角色只能存取自己的數據

{
  "X-Hasura-User-Id": "X-Hasura-User-Id"
}

內建即時訂閱機制（Subscription）

• 傳統 WebSocket 需自行實作，即時更新資料較為複雜。
• Hasura 內建 WebSocket，即時監聽資料庫變更，無需額外開發。

💡 即時監聽 users 更新

subscription {
  users {
    id
    name
    email
  }
}

綜合比較

說明

• 一般 GraphQL API 開發：需要手動撰寫 Schema、Resolvers、身份驗證、訂閱、權限管理等，較為靈活，但開發時間較長。
• Hasura：自動化大部分 GraphQL API 開發工作，省略 Resolvers、身份驗證、即時訂閱、存取權限等，適合快速開發應用程式。

如果你的專案需要高度客製化的 GraphQL API，一般後端開發 可能較適合；

如果你的專案主要是 CRUD（查詢/變更）型 API，且不需要複雜的後端邏輯，那麼 Hasura 會是一個更快的選擇！

如何安裝與使用 Hasura？

Hasura 提供多種安裝方式，可根據需求選擇合適的環境來運行。

透過 Docker 安裝 Hasura

Docker 是最常見的安裝方式，適用於本地開發環境或雲端部署。

步驟 1：建立 docker-compose.yml

version: "3.6"
services:
  postgres:
    image: postgres:13
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"

  hasura:
    image: hasura/graphql-engine:v2.0.0
    restart: always
    ports:
      - "8080:8080"
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://admin:password@postgres:5432/mydb
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_ADMIN_SECRET: mysecret
    depends_on:
      - postgres

步驟 2：啟動 Hasura

在終端機中執行：

docker-compose up -d

啟動後，Hasura Console（管理介面）可透過 http://localhost:8080 訪問。

設定資料庫並啟用 GraphQL API

進入 Hasura Console 後，按照以下步驟設定資料庫並開始使用 GraphQL API。

步驟 1：連接 PostgreSQL

在 Hasura Console 點擊 “Data” → “Connect Database”，輸入資料庫的連接字串，如：

postgres://admin:password@postgres:5432/mydb

步驟 2：建立資料表

進入 “Data” → “Create Table”，建立 users 資料表：

• id（UUID，主鍵，自動生成）
• name（Text，使用者名稱）
• email（Text，電子郵件）

點擊 “Save” 創建資料表。

步驟 3：測試 GraphQL API

進入 “GraphiQL”（Hasura 提供的 GraphQL 測試工具），輸入以下查詢：

query {
  users {
    id
    name
    email
  }
}

如果成功，Hasura 會返回 users 資料表中的所有資料。

設定存取權限（Permissions）

Hasura 允許開發者設定不同角色的存取權限，例如讓 訪客 只能讀取部分資料，而 管理員 可進行所有操作。

步驟 1：新增角色

進入 “Data” → “users” → “Permissions”，點擊 “Insert role” 並輸入 user。

步驟 2：設定讀取權限

• 選擇 Select 權限，僅允許讀取 id 和 name。
• 設定條件為 { id: X-Hasura-User-Id }，確保使用者只能查詢自己的資料。

步驟 3：設定寫入權限

• Insert 權限：允許新增 name 和 email。
• Update 權限：允許更新 name，但不能變更 email。

設定完成後，Hasura 會根據 X-Hasura-Role 標頭，自動應用對應的權限。

結語

Hasura 是一款強大且易用的 GraphQL 引擎，適合想要快速構建 API 的開發者。

透過本指南，你應該已經了解 Hasura 的基本概念、安裝方式、如何連接資料庫、設定 GraphQL API 以及管理存取權限。

如果你希望更進一步了解 Hasura，可以參考官方文件或試著將其部署到雲端服務（如 Heroku、AWS、GCP），開發更具規模的應用程式！