团子和蛋糕的笔记

Appearance

项目是什么 ​

汉字谜盒是一款基于人工智能的字谜互动游戏：AI 随机出一道经典字谜（如"一箭穿心"），你根据谜面猜字，AI 判断对错、给提示，最后揭晓答案。

项目结构 ​

text
汉字谜盒/
├── main.py            # FastAPI 服务端（所有接口）
├── static/            # 前端静态资源（从课程资料拷贝）
│   ├── index.html     # 页面结构
│   ├── app.js         # 前端逻辑（调用后端接口）
│   └── style.css      # 样式
└── sessions/          # 会话数据（每个会话一个 json 文件，程序自动创建）
    └── 2026-04-12_16-16-13.json

搭建第一步：创建项目文件夹，把课程资料里的 static 目录整个拷贝过来。

让根路径返回前端页面 ​

python
from fastapi import FastAPI
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles

app = FastAPI(title="汉字谜盒")

# 挂载静态文件目录
app.mount("/static", StaticFiles(directory="static"), name="static")

# 访问 http://localhost:8000/ 时返回前端页面
@app.get("/")
def root():
    return FileResponse("static/index.html")
参数含义
"/static"挂载路径：任何以 /static 开头的请求都交给这里处理
StaticFiles(directory="static")真实目录：HTML、CSS、JS 等静态资源存放的地方
name="static"FastAPI 内部使用的名称（可以自由定义）

NOTE

为什么要分成两个入口？

  • / 返回的是页面（index.html），所以用 FileResponse 把文件内容直接返回
  • 页面里的 /static/style.css、/static/app.js 这些请求交给 StaticFiles 处理 页面里引用资源时写的是 /static/xxx（绝对路径），这样静态资源就不会和接口路径打架。

前端是怎么调用后端的 ​

前端 app.js 里通过 fetch 调用后端接口，路径都以 /api 开头：

javascript
// 获取会话列表
const response = await fetch(`${API_BASE_URL}/sessions`);
// 加载指定会话
const response = await fetch(`${API_BASE_URL}/sessions/${sessionId}`);
// 新建会话 / 删除会话 / 与 AI 交互同理
前端请求对应后端接口
GET /api/sessions获取会话列表
POST /api/sessions新建会话
GET /api/sessions/{id}加载指定会话
DELETE /api/sessions/{id}删除会话
POST /api/chat与 AI 交互

相关 ​

练习题 ​

一、知识回顾（读完直接做下面的实践题） ​

  1. 汉字谜盒项目里 static/ 存放前端静态资源（HTML/CSS/JS），sessions/ 存放会话数据（json 文件）
  2. 让根路径返回前端页面用 FileResponse 响应类：return FileResponse("static/index.html")
  3. 挂载静态目录：app.mount("/static", StaticFiles(directory="static"), name="static")
  4. "/static" 是挂载路径，任何以它开头的请求都交给静态资源处理
  5. 页面里引用资源写成 /static/style.css（以 / 开头），是为了避免和**接口（API）**路径冲突
  6. 前端通过 fetch 调用接口，本项目所有接口路径都以 /api 开头

二、裸写题 ​

  • - 提示（先自己想，实在想不出再点开）

    一级 · 思路：一个入口返回页面，一个挂载点放静态资源 二级 · 方法：FileResponse / app.mount(...)三级 · 骨架：app.mount("/____", StaticFiles(directory="____"), name="static")

    - 参考答案（做完再点开）

    python
    from fastapi import FastAPI
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles

app = FastAPI(title="汉字谜盒")

# 2-1 挂载静态目录 + 首页返回页面
app.mount("/static", StaticFiles(directory="static"), name="static")

@app.get("/")
def root():
    return FileResponse("static/index.html")

  • - 提示（先自己想，实在想不出再点开）

    一级 · 思路：页面打不开通常是路径问题——先确认 static 是否在项目根目录 二级 · 方法：FileResponse("static/index.html") 里的路径是相对当前工作目录的 三级 · 骨架：用 TestClient 也能验证：client.get("/").status_code 应为 200

    - 参考答案（做完再点开）

    text
    # 在项目根目录下启动服务
fastapi dev main.py

# 浏览器打开 http://127.0.0.1:8000/     → 正常显示 static/index.html 页面
# 浏览器打开 http://127.0.0.1:8000/docs → FastAPI 自动生成的接口文档

  • - 提示（先自己想，实在想不出再点开）

    一级 · 思路：挂载点和页面入口都要能通 二级 · 方法：client.get("/static/style.css")三级 · 骨架：两个都应返回 200

    - 参考答案（做完再点开）

    python
    # 2-3 验证（需在项目根目录下运行，且 static/ 里已有文件）
from fastapi.testclient import TestClient

if __name__ == "__main__":
    client = TestClient(app)
    print("首页:", client.get("/").status_code)                 # 200
    print("样式:", client.get("/static/style.css").status_code)  # 200