从静态站点到全栈应用：一次 Astro 博客的前后端分离改造实践#

1
class Article(Base):
2
    __tablename__ = "articles"
3
    id = Column(Integer, primary_key=True, autoincrement=True)
4
    slug = Column(String(500), nullable=False, unique=True)
5
    title = Column(String(500), nullable=False)
6
    description = Column(Text, default="")
7
    content = Column(Text, nullable=False)
8
    published = Column(Date, nullable=False)
9
    updated = Column(Date, nullable=True)
10
    draft = Column(Boolean, default=False)
11
    tags = Column(JsonList, default=[])        # 自定义 JSON 列表类型
12
    category = Column(String(200), default="")
13
    lang = Column(String(20), default="")
14
    pinned = Column(Boolean, default=False)
15
    # ... 等 20+ 字段

1
class JsonList(TypeDecorator):
2
    impl = Text
3
    cache_ok = True
4

5
    def process_bind_param(self, value, dialect):
6
        if value is None:
7
            return "[]"
8
        return json.dumps(value, ensure_ascii=False)
9

10
    def process_result_value(self, value, dialect):
11
        if value is None:
12
            return []
13
        return json.loads(value)

1
class User(Base):
2
    __tablename__ = "users"
3
    id = Column(Integer, primary_key=True, autoincrement=True)
4
    username = Column(String(100), nullable=False, unique=True)
5
    role = Column(String(20), default="visitor", nullable=False)  # admin | visitor
6
    email = Column(String(200), nullable=False, unique=True)
7
    password = Column(String(255), nullable=False)  # bcrypt 哈希

1
order_case = case((Article.pinned == True, 0), else_=1)
2

3
query = base_query.order_by(
4
    order_case,                                    # 第一级：置顶文章优先
5
    case((Article.priority.is_(None), 1), else_=0), # 第二级：有优先级的优先
6
    Article.priority.asc(),                         # 置顶内按优先级升序
7
    Article.published.desc()                        # 第三级：按发布日期降序
8
)

1
class ArticleOut(BaseModel):
2
    id: int
3
    slug: str
4
    title: str
5
    content: str
6
    tags: list[str] = []
7
    # ...
8
    model_config = {"from_attributes": True}  # 关键：兼容 ORM 对象
9

10
class ArticleListOut(BaseModel):
11
    articles: list[ArticleOut]
12
    total: int
13
    page: int
14
    page_size: int
15
    total_pages: int

1
const BACKEND_URL = import.meta.env.BACKEND_URL || "http://localhost:8000";
2

3
async function apiFetch<T>(path: string, params?: Record<string, string>): Promise<T> {
4
    const url = new URL(path, BACKEND_URL);
5
    if (params) {
6
        Object.entries(params).forEach(([key, value]) => {
7
            url.searchParams.set(key, value);
8
        });
9
    }
10
    const response = await fetch(url.toString());
11
    if (!response.ok) {
12
        throw new Error(`API error: ${response.status} ${response.statusText} for ${url}`);
13
    }
14
    return response.json() as Promise<T>;
15
}

1
export async function fetchArticles(params: ArticleListParams = {}): Promise<ArticleListResponse> {
2
    try {
3
        return await apiFetch<ArticleListResponse>("/api/articles", queryParams);
4
    } catch (e) {
5
        if (isBackendError(e)) {
6
            console.warn("Backend API unavailable, using empty article list");
7
            return { articles: [], total: 0, page: 1, page_size: params.page_size || 10, total_pages: 0 };
8
        }
9
        throw e;
10
    }
11
}

1
# 核心逻辑：检查 slug → 更新或创建 → 提交
2
stmt = select(Article).where(Article.slug == data["slug"])
3
existing = result.scalar_one_or_none()
4
if existing:
5
    for key, value in data.items():
6
        setattr(existing, key, value)  # 更新已有记录
7
else:
8
    session.add(Article(**data))  # 插入新记录
9
await session.commit()

1
// 改造前（静态模式）
2
export async function getStaticPaths() {
3
    const posts = await getSortedPosts();  // 从本地文件系统读取
4
    // 生成 1..totalPages 的静态页面
5
}

1
// 改造后（SSR 模式）
2
const page = Number(Astro.params.page) || 1;
3
const result = await fetchArticles({ page, page_size: pageSize });
4
// 动态分页，无需预生成所有页面

1
remark-parse → remark-gfm → remark-math → remark-directive →
2
remark-sectionize → remark-rehype → rehype-expressive-code →
3
rehype-katex → rehype-slug → rehype-autolink-headings → rehype-stringify

1
---
2
// 服务端过滤和分组逻辑
3
const activeTags = Astro.url.searchParams.getAll("tag");
4
const activeCategories = Astro.url.searchParams.getAll("category");
5

6
let filteredPosts = posts;
7
if (activeTags.length > 0) {
8
    filteredPosts = filteredPosts.filter(post =>
9
        post.data.tags.some(tag => activeTags.includes(tag))
10
    );
11
}
12

13
// 按年份分组，按时间排序
14
filteredPosts = [...filteredPosts].sort(
15
    (a, b) => new Date(b.data.published).getTime() - new Date(a.data.published).getTime()
16
);
17

18
const grouped: Record<number, PostForList[]> = {};
19
for (const post of filteredPosts) {
20
    const year = new Date(post.data.published).getFullYear();
21
    if (!grouped[year]) grouped[year] = [];
22
    grouped[year].push(post);
23
}
24
---

1
SECRET_KEY = os.getenv("JWT_SECRET", "fallback-secret-change-me")
2
ALGORITHM = "HS256"
3
ACCESS_TOKEN_EXPIRE_MINUTES = int(os.getenv("ACCESS_TOKEN_EXPIRE_MINUTES", "1440"))
4

5
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/users/login")
6

7
def create_access_token(data: dict) -> str:
8
    to_encode = data.copy()
9
    expire = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
10
    to_encode.update({"exp": expire})
11
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

1
OAuth2PasswordBearer (提取 Token)
2
    → get_current_user (验证 Token → 查询用户)
3
        → require_admin (检查 role == "admin")

1
async def require_admin(user: User = Depends(get_current_user)) -> User:
2
    if user.role != "admin":
3
        raise HTTPException(status_code=403, detail="Admin privileges required")
4
    return user

1
@router.post("/articles", response_model=ArticleOut)
2
async def create_article(
3
    article_data: ArticleCreate,
4
    session: AsyncSession = Depends(get_session),
5
    current_user: User = Depends(require_admin),  # 自动校验管理员权限
6
):
7
    # ...

1
// 基于 module-level 闭包变量实现单例状态
2
let accessToken: string | null = initial.accessToken;
3
let user: UserInfo | null = initial.user;
4

5
// localStorage 持久化，页面刷新不丢失登录态
6
function loadFromStorage(): AuthState {
7
    const token = localStorage.getItem("mizuki_access_token");
8
    const userStr = localStorage.getItem("mizuki_user");
9
    // ...
10
}
11

12
// 登录成功后通过 CustomEvent 通知其他组件
13
function login(loginValue: string, password: string): Promise<void> {
14
    // ...
15
    document.dispatchEvent(new CustomEvent("user-login-changed"));
16
}

1
async function authenticatedFetch(url: string, options: RequestInit): Promise<Response> {
2
    const headers = { ...getAuthHeaders(), ...options.headers };
3
    let response = await fetch(url, { ...options, headers });
4

5
    // 401 时自动尝试刷新 Token 并重试一次
6
    if (response.status === 401) {
7
        const newToken = await refreshToken();
8
        if (newToken) {
9
            const retryHeaders = { ...headers, Authorization: `Bearer ${newToken}` };
10
            return fetch(url, { ...options, headers: retryHeaders });
11
        }
12
    }
13
    return response;
14
}

1
{entry.adminOnly && !isAdmin() ? null : (
2
    <a href={entry.url}>{entry.label}</a>
3
)}

1
---
2
// src/pages/admin/articles.astro（重构后）
3
---
4
<Layout>
5
    <ArticleManager />
6
</Layout>

1
class ArticleEditorUI {
2
    constructor(root) {
3
        this.root = root;
4
        this.title = "";
5
        this.slug = "";
6
        // ... 状态变量
7
        this.render();  // 首次渲染
8
    }
9

10
    render() {
11
        // 根据状态拼接 HTML 字符串并设置 innerHTML
12
        this.root.innerHTML = `
13
            <form>
14
                <input id="ae-title" value="${this.attrEscape(this.title)}" />
15
                <!-- ... -->
16
            </form>
17
        `;
18
        this.bindEvents();  // 重新绑定事件监听
19
    }
20

21
    bindEvents() {
22
        // querySelector + addEventListener
23
    }
24
}

1
<div id="article-manager-root" data-backend-url={BACKEND_URL}>
2
</div>
3

4
<script is:inline>
5
    var rootEl = document.getElementById("article-manager-root");
6
    var BACKEND_URL = rootEl ? rootEl.dataset.backendUrl : "";
7
</script>

1
═══════════════════════════════════════════════════
2
                    改造前（纯静态）
3
═══════════════════════════════════════════════════
4
  Markdown 文件 → Astro Content Collections
5
    → 构建时生成 → 静态 HTML（部署到 CDN/静态托管）
6

7
  特点：零服务器成本、极快响应、无数据库依赖
8
  局限：无动态内容、无用户系统、更新需重新构建部署
9
═══════════════════════════════════════════════════
10

11
═══════════════════════════════════════════════════
12
                    改造后（前后端分离）
13
═══════════════════════════════════════════════════
14
  ┌─────────────────────────────────────────────┐
15
  │               前端（Astro SSR）               │
16
  │  ┌─────────┐ ┌──────────┐ ┌──────────────┐  │
17
  │  │ 公开页面 │ │ 管理后台  │ │ 组件层       │  │
18
  │  │ (SSR)   │ │ (内联JS) │ │ (纯Astro)    │  │
19
  │  └────┬────┘ └────┬─────┘ └──────────────┘  │
20
  │       │           │                          │
21
  │       └─────┬─────┘                          │
22
  │             │ HTTP fetch                      │
23
  └─────────────┼────────────────────────────────┘
24
                │
25
  ┌─────────────┼────────────────────────────────┐
26
  │             ▼          后端（Python FastAPI） │
27
  │  ┌──────────────────────────────────────┐    │
28
  │  │            FastAPI Application         │    │
29
  │  │  ┌──────────┐  ┌──────────────────┐   │    │
30
  │  │  │ JWT Auth │  │  Article Router  │   │    │
31
  │  │  │ (HS256)  │  │  (RESTful CRUD)  │   │    │
32
  │  │  └──────────┘  └────────┬─────────┘   │    │
33
  │  │  ┌──────────┐  ┌───────┴──────────┐  │    │
34
  │  │  │User Router│  │ Pydantic Schema  │  │    │
35
  │  │  │(CRUD)    │  │ (Validation)     │  │    │
36
  │  │  └──────────┘  └──────────────────┘  │    │
37
  │  └────────────────┬─────────────────────┘    │
38
  │                   │                           │
39
  │  ┌────────────────▼─────────────────────┐    │
40
  │  │   SQLAlchemy Async + SQLite          │    │
41
  │  │   (ORM + 连接池)                      │    │
42
  │  └──────────────────────────────────────┘    │
43
  └──────────────────────────────────────────────┘