1. 什麼是 Node.js? / What is Node.js?

1.1 如何安裝 Node.js / How to Install Node.js

# 檢查 Node.js 版本 / Check Node.js version
node -v

# 檢查 NPM 版本 / Check NPM version
npm -v
        

1.2 Node.js 不是瀏覽器 / Node.js is NOT a Browser

// 這段程式碼在 Node.js 會直接報錯
console.log(document.title);

1.3 為什麼 Node.js 適合高併發 / Why Node.js Handles Concurrency Well

1.4 Node.js 的典型使用場景 / Common Use Cases

1.5 什麼情況不適合使用 Node.js / When NOT to Use Node.js

2. 同步 vs 非同步 / Sync vs Async

❌ 同步做法 / Synchronous (Blocking)

const fs = require('fs');

// 讀取檔案時會卡住 / Execution stops here until file is read
const data = fs.readFileSync('file.txt'); 

console.log(data);
console.log('最後才執行 / Runs last');
        

✅ 非同步做法 / Asynchronous (Non-blocking)

const fs = require('fs');

fs.readFile('file.txt', (err, data) => {
    if (err) throw err;
    console.log('檔案讀完才跑這 / Runs after file is read');
});

console.log('我會先被執行 / I will run first!');
        

2.1 為什麼同步在伺服器是危險的 / Why Sync is Dangerous on Servers

// ❌ 錯誤示範：同步阻塞
app.get('/data', (req, res) => {
  const data = fs.readFileSync('big.json');
  res.send(data);
});

2.2 Callback Hell 是怎麼誕生的 / How Callback Hell Happens

// ❌ Callback Hell
login(user, () => {
  getProfile(() => {
    getOrders(() => {
      sendResponse();
    });
  });
});

2.3 Promise 的出現 / The Rise of Promises

login(user)
  .then(getProfile)
  .then(getOrders)
  .then(sendResponse)
  .catch(handleError);

2.4 async / await 的真正意義 / What async/await Really Means

async function handler() {
  const user = await login();
  const profile = await getProfile(user);
  return profile;
}

2.5 async/await 地獄 / async-await Hell

// ❌ 效能陷阱（每個 await 都在等）
for (const id of ids) {
  const data = await fetchData(id);
  console.log(data);
}

2.6 正確處理多個非同步任務 / Handling Async Tasks Properly

// ✅ 正確做法
const results = await Promise.all(
  ids.map(id => fetchData(id))
);

3. 事件循環 / Event Loop

3.1 Event Loop 在做什麼 / What Does the Event Loop Do?

3.2 Call Stack 與 Task Queue / Call Stack & Task Queue

[ Call Stack ]
| main()     |
| foo()      |
| bar()      |
--------------
(Call Stack must be empty first)

3.3 Microtask vs Macrotask

3.4 Event Loop 執行流程 / Execution Flow

1️⃣ 執行 Call Stack（同步程式碼）
2️⃣ Call Stack 清空
3️⃣ 清空所有 Microtask Queue
4️⃣ 執行一個 Macrotask
5️⃣ 回到第 2 步（無限循環）

3.5 經典考題：console.log 順序解析

console.log('A');

setTimeout(() => {
  console.log('B');
}, 0);

Promise.resolve().then(() => {
  console.log('C');
});

console.log('D');

4. 第一個伺服器 / Your First Server

const http = require('http');

const server = http.createServer((req, res) => {
    // 設定回應標頭 / Set response header
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello from Node.js!');
});

server.listen(3000, () => {
    console.log('Server running at http://localhost:3000/');
});
        

5. Express 請求全流程 / Express Request Lifecycle

5.1 一個請求進來時，發生了什麼？ / What Happens on a Request

Request
  ↓
Middleware（依註冊順序）
  ↓
Route Handler
  ↓
Response

5.2 Middleware 的真正角色 / What Middleware Really Is

5.3 Middleware 執行順序 / Execution Order

app.use(logger);
app.use(auth);

app.get('/profile', handler);

5.4 next() 的真正意義 / What next() Really Does

app.use((req, res, next) => {
  console.log('檢查完成');
  next();
});

5.5 Route Handler 是終點 / Route Handler as the Endpoint

app.get('/api/user', (req, res) => {
  res.json({ name: 'Tom' });
});

5.6 錯誤在 Express 中怎麼流動？

app.use((req, res, next) => {
  next(new Error('爆炸'));
});

Request
  ↓
Middleware
  ↓
❌ Error
  ↑
Error Middleware（4 個參數）

5.7 Express Request Lifecycle（總覽）

Client Request
   ↓
Global Middleware
   ↓
Route Middleware
   ↓
Route Handler
   ↓
Response Sent
   ↓
（若發生錯誤）
   ↑
Error Middleware

5.8 本章重點總結 / Key Takeaways

• ✅ Middleware 是一條「管線」
• ✅ 順序錯，整個系統就錯
• ✅ next() 是流程控制，不是裝飾
• ✅ 錯誤一定要送到 Error Middleware

6. REST API 實戰 / REST API CRUD

// 取得所有項目 (Read) / Get all items
app.get('/api/items', (req, res) => {
    res.json({ message: "獲取所有資料" });
});

// 建立新項目 (Create) / Create new item
app.post('/api/items', (req, res) => {
    res.status(201).json({ message: "資料已建立" });
});

// 更新項目 (Update) / Update item
app.put('/api/items/:id', (req, res) => {
    const id = req.params.id;
    res.json({ message: `ID ${id} 已更新` });
});

// 刪除項目 (Delete) / Delete item
app.delete('/api/items/:id', (req, res) => {
    res.json({ message: "資料已刪除" });
});
        

6.1 專案目標 / Project Goal

6.2 專案結構 / Project Structure

todo-api/
 ├─ app.js
 ├─ server.js
 ├─ routes/
 │   └─ todos.js
 ├─ controllers/
 │   └─ todoController.js
 ├─ middleware/
 │   └─ errorHandler.js
 └─ data/
     └─ todos.json

6.3 Server 啟動點 / server.js

const app = require('./app');

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

6.4 Express App 管線 / app.js

const express = require('express');
const todoRoutes = require('./routes/todos');
const errorHandler = require('./middleware/errorHandler');

const app = express();

app.use(express.json());
app.use('/api/todos', todoRoutes);

// 一定放最後
app.use(errorHandler);

module.exports = app;

6.5 Routes / routes/todos.js

const express = require('express');
const router = express.Router();
const controller = require('../controllers/todoController');

router.get('/', controller.getAll);
router.post('/', controller.create);
router.put('/:id', controller.update);
router.delete('/:id', controller.remove);

module.exports = router;

6.6 Controller / controllers/todoController.js

let todos = [];

exports.getAll = async (req, res) => {
  res.json(todos);
};

exports.create = async (req, res) => {
  const todo = { id: Date.now(), title: req.body.title };
  todos.push(todo);
  res.status(201).json(todo);
};

exports.update = async (req, res) => {
  const todo = todos.find(t => t.id == req.params.id);
  if (!todo) throw new Error('Todo not found');
  todo.title = req.body.title;
  res.status(200).json({
  success: true,
  data: todo
});

exports.remove = async (req, res) => {
  todos = todos.filter(t => t.id != req.params.id);
  res.status(204).end();
};

6.7 Error Middleware / middleware/errorHandler.js

module.exports = (err, req, res, next) => {
  console.error(err.message);
  res.status(500).json({ error: err.message });
};

6.8 一次 API 請求全流程回顧

Client
 ↓
express.json()
 ↓
/api/todos Router
 ↓
Controller (async)
 ↓
Response
 ↓
（錯誤時）
 ↓
Error Middleware

6.9 本章你學到什麼？

• ✔ Express 專案怎麼拆
• ✔ Middleware 正確位置
• ✔ async/await 真實使用場景
• ✔ 錯誤不會再炸 server

7. API 設計原則與實務 / API Design Best Practices

7.1 什麼是好的 API？ / What Makes a Good API

7.2 REST 命名慣例 / RESTful Naming

GET    /api/todos        → 取得清單
POST   /api/todos        → 新增
GET    /api/todos/:id    → 取得單筆
PUT    /api/todos/:id    → 更新
DELETE /api/todos/:id    → 刪除

7.3 HTTP Status Code 使用原則

7.4 API Response 格式設計

// 成功
{
  "success": true,
  "data": {...}
}

// 失敗
{
  "success": false,
  "error": {
    "message": "Todo not found"
  }
}

7.5 錯誤回應設計 / Error Response

throw {
  status: 404,
  message: 'Todo not found'
};

7.6 用「API 使用者」的腦袋設計

• 前端要不要猜狀態？
• 錯誤好不好顯示給使用者？
• 每支 API 回傳是不是長一樣？

7.7 本章重點

• ✔ REST 命名是第一印象
• ✔ Status Code 是溝通工具
• ✔ Response 結構要固定
• ✔ 錯誤也是 API 的一部分

8. 環境變數與部署思維 / Environment & Deployment

# 安裝 dotenv 套件 / Install dotenv package
npm install dotenv
        

require('dotenv').config();

const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;

console.log(`Port is: ${port}`);
        

8.1 為什麼要分環境？ / Why Environments Matter

8.2 Hard Code 是災難 / Never Hard Code Secrets

const PORT = 3000;
const DB_PASSWORD = '123456';

8.3 使用 dotenv / Using dotenv

npm install dotenv

8.4 根據 NODE_ENV 調整行為

if (process.env.NODE_ENV === 'production') {
  console.log = () => {};
}

8.5 Production Error Handling

module.exports = (err, req, res, next) => {
  const isProd = process.env.NODE_ENV === 'production';

  res.status(err.status || 500).json({
    success: false,
    error: {
      message: isProd ? 'Server error' : err.message
    }
  });
};

8.6 Deployment Checklist

• ✔ 所有設定來自 process.env
• ✔ 沒有 hard code 密碼
• ✔ Error handler 已區分 production
• ✔ 專案可用 npm start 啟動

8.7 工程師思維轉換

8.8 Nodebook Final Summary

• 你理解了 Node.js 的非同步模型
• 你掌握了 Express 的請求生命週期
• 你能設計一致的 REST API
• 你知道如何準備一個可部署的後端

9. 接上 MongoDB：真正的後端資料層 / MongoDB Integration

9.1 為什麼使用 MongoDB？ / Why MongoDB

9.2 安裝 MongoDB Driver（Mongoose）

npm install mongoose

9.3 MongoDB 連線設定 / Database Connection

// config/db.js
const mongoose = require('mongoose');

module.exports = async function connectDB() {
  try {
    await mongoose.connect(process.env.MONGO_URI);
    console.log('MongoDB connected');
  } catch (err) {
    console.error(err);
    process.exit(1);
  }
};

9.4 啟動時連線資料庫

// server.js
require('dotenv').config();
const connectDB = require('./config/db');
const app = require('./app');

connectDB();

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

9.5 定義 Model / Mongoose Schema

// models/Todo.js
const mongoose = require('mongoose');

const TodoSchema = new mongoose.Schema({
  title: {
    type: String,
    required: true
  },
  completed: {
    type: Boolean,
    default: false
  }
}, {
  timestamps: true
});

module.exports = mongoose.model('Todo', TodoSchema);

9.6 使用 MongoDB 重構 Controller

// controllers/todoController.js
const Todo = require('../models/Todo');

exports.getAll = async (req, res, next) => {
  try {
    const todos = await Todo.find();
    res.json({ success: true, data: todos });
  } catch (err) {
    next(err);
  }
};

exports.create = async (req, res, next) => {
  try {
    const todo = await Todo.create({ title: req.body.title });
    res.status(201).json({ success: true, data: todo });
  } catch (err) {
    next(err);
  }
};

exports.update = async (req, res, next) => {
  try {
    const todo = await Todo.findByIdAndUpdate(
      req.params.id,
      req.body,
      { new: true }
    );

    if (!todo) {
      return next({ status: 404, message: 'Todo not found' });
    }

    res.json({ success: true, data: todo });
  } catch (err) {
    next(err);
  }
};

exports.remove = async (req, res, next) => {
  try {
    const todo = await Todo.findByIdAndDelete(req.params.id);
    if (!todo) {
      return next({ status: 404, message: 'Todo not found' });
    }
    res.status(204).end();
  } catch (err) {
    next(err);
  }
};

9.7 真正的非同步 I/O

9.8 含 MongoDB 的請求生命週期

Client
 ↓
Express Middleware
 ↓
Controller (await MongoDB)
 ↓
MongoDB I/O
 ↓
Response

9.9 本章總結

• ✔ Model / Controller / Route 分層
• ✔ 真實資料庫 CRUD
• ✔ async/await + Error Middleware
• ✔ 可長期運作的後端架構

10. JWT 認證流程（真正可用的後端） / JWT Authentication

10.1 JWT 是什麼？ / What is JWT

10.2 JWT Login Flow

User Login
 ↓
Verify Password
 ↓
Server signs JWT
 ↓
Client stores token
 ↓
Client sends token in Authorization header
 ↓
Server verifies token

10.3 安裝認證套件

npm install jsonwebtoken bcryptjs

10.4 User Model / models/User.js

const mongoose = require('mongoose');

const UserSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true
  },
  password: {
    type: String,
    required: true
  }
});

module.exports = mongoose.model('User', UserSchema);

10.5 Register API

// controllers/authController.js
const User = require('../models/User');
const bcrypt = require('bcryptjs');

exports.register = async (req, res, next) => {
  try {
    const hashed = await bcrypt.hash(req.body.password, 10);
    const user = await User.create({
      email: req.body.email,
      password: hashed
    });

    res.status(201).json({ success: true });
  } catch (err) {
    next(err);
  }
};

10.6 Login + Sign JWT

const jwt = require('jsonwebtoken');

exports.login = async (req, res, next) => {
  try {
    const user = await User.findOne({ email: req.body.email });
    if (!user) {
      return next({ status: 401, message: 'Invalid credentials' });
    }

    const match = await bcrypt.compare(req.body.password, user.password);
    if (!match) {
      return next({ status: 401, message: 'Invalid credentials' });
    }

    const token = jwt.sign(
      { userId: user._id },
      process.env.JWT_SECRET,
      { expiresIn: '1h' }
    );

    res.json({ success: true, token });
  } catch (err) {
    next(err);
  }
};

10.7 Auth Middleware / middleware/auth.js

const jwt = require('jsonwebtoken');

module.exports = (req, res, next) => {
  const auth = req.headers.authorization;
  if (!auth || !auth.startsWith('Bearer ')) {
    return next({ status: 401, message: 'No token' });
  }

  const token = auth.split(' ')[1];

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.userId = decoded.userId;
    next();
  } catch {
    next({ status: 401, message: 'Invalid token' });
  }
};

10.8 Protect Routes

// routes/todos.js
const auth = require('../middleware/auth');

router.use(auth);

10.9 JWT 常見錯誤

• ❌ 把 JWT 存在 localStorage（XSS 風險）Do not store JWTs in localStorage (XSS risk)
• ❌ Token 不設過期時間 Do not set an expiration time for tokens
• ❌ 在 JWT 裡放敏感資料 Do not put sensitive data in JWTs

10.10 本章總結

• ✔ 密碼一定要 hash
• ✔ JWT 無狀態、可擴充
• ✔ Auth Middleware 是防線
• ✔ 這已是正式後端架構

11. 使用 ngrok 公開網站 / Expose with ngrok

步驟 1: 啟動你的 Node.js 伺服器 / Step 1: Start Server

node app.js
# Output: Server running at http://localhost:3000/
        

步驟 2: 啟動 ngrok / Step 2: Run ngrok

# 如果你有安裝 ngrok 軟體
ngrok http 3000

# 或者使用 npx (無需安裝) / Or use npx (no install needed)
npx ngrok http 3000
        

步驟 3: 獲得網址 / Step 3: Get URL

Session Status                online
Account                       Your Name (Plan: Free)
Forwarding                    https://random-name.ngrok-free.app -> http://localhost:3000
Web Interface                 http://127.0.0.1:4040
        

12. API Security Hardening（真正可上線的防禦）

12.1 Zero Trust 原則

12.2 Rate Limiting

npm install express-rate-limit

12.3 使用 Helmet

npm install helmet

12.4 正確設定 CORS

npm install cors

12.5 防止 NoSQL Injection

npm install express-mongo-sanitize

12.6 Error 資訊最小化

if (process.env.NODE_ENV === 'production') {
  err.message = 'Server error';
}

12.7 Middleware 載入順序

helmet
 ↓
rateLimit
 ↓
cors
 ↓
mongoSanitize
 ↓
routes
 ↓
errorHandler

12.8 Security Checklist

• ✔ Rate Limit 已開
• ✔ JWT 有 expiry
• ✔ CORS 非全開
• ✔ Error 資訊最小化
• ✔ 沒有 hard-coded secret

12.9 最重要的一句話

功能錯誤會被發現， 安全漏洞會被利用。 Functional errors will be discovered, and security vulnerabilities will be exploited.

13. API 分頁、搜尋、排序（Product-grade API）

13.1 為什麼需要 Pagination？

13.2 Query Parameter 設計

GET /api/todos
  ?page=1
  &limit=10
  &sort=createdAt
  &order=desc
  &q=learn

13.3 Todo 查詢 Controller（Pagination + Search + Sort）

exports.getAll = async (req, res, next) => {
  try {
    const page = Math.max(parseInt(req.query.page) || 1, 1);
    const limit = Math.min(parseInt(req.query.limit) || 10, 100);
    const skip = (page - 1) * limit;

    const sortField = req.query.sort || 'createdAt';
    const sortOrder = req.query.order === 'asc' ? 1 : -1;

    const query = {};

    if (req.query.q) {
      query.title = { $regex: req.query.q, $options: 'i' };
    }

    const [todos, total] = await Promise.all([
      Todo.find(query)
        .sort({ [sortField]: sortOrder })
        .skip(skip)
        .limit(limit),
      Todo.countDocuments(query)
    ]);

    res.json({
      success: true,
      data: todos,
      meta: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit)
      }
    });
  } catch (err) {
    next(err);
  }
};

13.4 Response Meta 設計

{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

13.5 搜尋效能注意事項 (Search performance considerations)

• Regex 搜尋適合小型專案 Regex。 searches are suitable for small projects.
• 正式產品應使用 Text Index。 Production should use a text index.
• 避免讓使用者自由指定 sort 欄位。 void letting users freely specify the sort field.

13.6 Sort 欄位白名單

const allowedSortFields = ['createdAt', 'title'];

const sortField = allowedSortFields.includes(req.query.sort)
  ? req.query.sort
  : 'createdAt';

13.7 API 使用範例

GET /api/todos?page=2&limit=5&q=node&sort=createdAt&order=desc

13.8 常見錯誤

• ❌ 一次回傳全部資料 (All data returned at once)
• ❌ 沒有 meta 資訊 (No meta information)
• ❌ query 參數未驗證 (Query parameters not validated)

13.9 本章總結

• ✔ Pagination 是必須
• ✔ Search / Sort 提升 UX
• ✔ Meta 是 API 契約
• ✔ 這已是產品級 API