「Flask + MongoDB」REST API 最小實作與使用說明

 這是一套「Flask + MongoDB」REST API 最小實作與使用說明。

可直接套到你現有的 MongoDB docker-compose。

專案結構

flask-mongo-api/
├─ app.py
├─ requirements.txt
├─ .env.example
├─ Dockerfile
└─ docker-compose.yml   # 可選；若你已有 mongodb compose，就只補一個 app 服務

requirements.txt

Flask==3.0.3
pymongo==4.8.0
python-dotenv==1.0.1

.env.example

FLASK_ENV=production
PORT=8000
MONGO_URI=mongodb://mongo:27017/appdb
DB_NAME=appdb
COLL_NAME=items
API_KEY=changeme123

Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
ENV PORT=8000
EXPOSE 8000
CMD ["python", "app.py"]


docker-compose.yml（含 app 與 mongo，
若你已有 MongoDB，
只保留 app 區段並對上你的網路與環境變數）

version: "3.9"
services:
  mongo:
    image: mongo:7
    restart: unless-stopped
    ports: ["27017:27017"]
    volumes:
      - mongo_data:/data/db

  api:
    build: .
    depends_on: [mongo]
    environment:
      - MONGO_URI=mongodb://mongo:27017/appdb
      - DB_NAME=appdb
      - COLL_NAME=items
      - API_KEY=changeme123
      - PORT=8000
    ports: ["8000:8000"]
    restart: unless-stopped

volumes:
  mongo_data:




啟動
cp .env.example .env   # 可選
docker compose up -d --build
# 或本機
pip install -r requirements.txt
python app.py

範例資料格式
{
  "title": "sample",
  "price": 1200,
  "tags": ["demo","v1"],
  "meta": {"brand":"abc","color":"black"}
}

範例請求（curl）
# 健康檢查
curl -H "X-API-Key: changeme123" http://localhost:8000/health

# 建立
curl -X POST http://localhost:8000/api/v1/items \
  -H "Content-Type: application/json" -H "X-API-Key: changeme123" \
  -d '{"title":"sample","price":1200,"tags":["demo","v1"]}'

# 分頁查詢（全文 + 標籤 + 時間窗）
curl -G http://localhost:8000/api/v1/items \
  -H "X-API-Key: changeme123" \
  --data-urlencode "q=sample" \
  --data-urlencode "tag=demo" \
  --data-urlencode "page=1" \
  --data-urlencode "size=10"

# 取單筆
curl -H "X-API-Key: changeme123" http://localhost:8000/api/v1/items/<_id>

# 更新
curl -X PATCH http://localhost:8000/api/v1/items/<_id> \
  -H "Content-Type: application/json" -H "X-API-Key: changeme123" \
  -d '{"price":1399,"tags":["demo","v2"]}'

# 刪除
curl -X DELETE -H "X-API-Key: changeme123" http://localhost:8000/api/v1/items/<_id>

# 批次新增
curl -X POST http://localhost:8000/api/v1/items/bulk \
  -H "Content-Type: application/json" -H "X-API-Key: changeme123" \
  -d '[{"title":"a"},{"title":"b","tags":["x"]}]'

# 聚合（每個 tag 的件數）
curl -X POST http://localhost:8000/api/v1/items/aggregate \
  -H "Content-Type: application/json" -H "X-API-Key: changeme123" \
  -d '[{"$unwind":"$tags"},{"$group":{"_id":"$tags","count":{"$sum":1}}},{"$sort":{"count":-1}}]'

與你現有 MongoDB compose 整合

若你已有 /mnt/data/docker-compose-mongodb.yml，保持該 mongo 服務不變。
在你的 compose 加入 api 服務區塊，MONGO_URI 指向現有 mongo 服務名稱與資料庫名稱
確保兩服務在同一個 docker network。
最小實務建議

加 API_KEY 或反向代理層驗證。必要時加 JWT。

對高頻欄位建立索引（已示範 created_at、tags、全文 q）。

以 ISO8601 處理時間欄位。用 UTC。

生產環境加備援連線字串與寫入關聯（Replica Set）。