前后端分离通讯录管理系统设计与实现

[FDSCE001]

前后端分离通讯录管理系统设计与实现

作者：孙晨恩
学号：832301113（FZU） 23126418(MU)
一、项目背景与技术栈
技术栈说明

通讯：FastAPI、Pydantic、SQLAlchemy（来自文件名推断）
运行：Uvicorn（常见于FastAPI，若用其他服务器请替换）
数据库：以 SQLAlchemy 为 ORM，默认可对接 SQLite/MySQL/PostgreSQL
静态：纯静态页面（static/contacts/index.html），通过浏览器访问

模块 技术 / 框架 作用
前端 原生 HTML/CSS/JS (static/contacts/index.html) 构建交互页面，调用后端接口，展示联系人列表与表单提交
后端 FastAPI (app/main.py, app/routers/contacts.py) 提供 RESTful API (/contacts 等)，路由与请求处理
数据访问 SQLAlchemy (app/models.py, app/crud.py) 定义 ORM 模型与 CRUD 封装，读写数据库
数据校验 Pydantic (app/schemas.py) 请求 / 响应数据校验与序列化
数据库 SQLite (可换 MySQL/PostgreSQL) 持久化存储联系人信息
运行服务 Uvicorn 启动 ASGI 服务，承载 FastAPI 应用
静态托管 StaticFiles 将 static 目录暴露为 /static
跨域 CORSMiddleware 本地开发允许前端跨域访问 API

项目目的说明

阶段 任务分类 详细说明 预计运行时间 (小时) 实际运行 (小时)
计划阶段 项目规划 明确目标与范围，确定接口与页面功能，制定流程与分工 1.0 1.0
计划阶段 技术选型 FastAPI、SQLAlchemy、Pydantic、SQLite、Uvicorn、静态仓库、CORS 0.5 0.3
设计阶段 需求分析 确认字段：id、name、email、phone、created_at； 列表 / 搜索 / 增删改 1.5 1.2
设计阶段 接口设计 /contacts GET/POST/PUT/DELETE，/stats GET； 请求 / 响应体定义 2.0 1.8
设计阶段 数据库设计 Contact 表结构与索引 (email 唯一)； 启动建表或迁移策略 1.0 0.8
开发阶段 环境搭建 脚手架、依赖、运行脚本 (uvicorn app.main:app --reload) 1.0 0.8
开发阶段 模型与模式 models.py 与 schemas.py 提供实体与验证 2.0 1.6
开发阶段 数据访问层 crud.py：创建 / 列表 / 获取 / 更新 / 删除，分页与查询 3.0 2.5
开发阶段 路由与控制器 routers/contacts.py 与 app/main.py 注册； 异常与返回格式 2.5 2.0
开发阶段 数据库接入 数据库.py 引擎 / 会话； 启动建表与连接测试 1.0 0.8
开发阶段 静态托管 挂载 / 静态； 加密路径与编码； 访问 index.html 0.8 0.6
开发阶段 前端页面 static/contacts/index.html: 表单、列表、按钮与样式 2.0 1.7
开发阶段 前端交换 获取调用 API； 加载状态、错误提示、列表刷新 2.5 2.0
开发阶段 跨域与安全 CORS 配置； 输入校验与错误码排列 0.8 0.6
测试阶段 接口联调 Postman/HTTPie 覆盖 CRUD 与异常示例； 分页 / 搜索验证 2.0 1.6
测试阶段 页面测试 新增 / 编辑 / 删除 / 搜索结果验证； 边界与异常提示 1.5 1.2
部署阶段 本地部署 Uvicorn + SQLite 一体化运行； /docs 校验； 静态可访问 1.0 0.8
文档阶段 接口文档 OpenAPI 校对； 补充字段说明和示例 1.0 0.8
文档阶段 使用说明 README: 目录、命令、配置、常见问题 1.0 0.8
复盘阶段 问题总结 跨域、路径、权限等问题与解决； 后续优化计划 0.8 0.6
合计 — 总开发时长 26.9 22.1

构建以太网管理的最大可用仓库 API 和一个静态以太网页
说明语音的目录拆分与职责边界，后续扩展
二、项目结构设计
实际目录

应用程序/
路由器/
contacts.py
初始化.py
crud.py
数据库.py
初始化.py
main.py
models.py
schemas.py
static/ ←注意：这里虽然叫static，但内部是Python（内部）代码
静止的/
联系方式/
index.html ← 前端页面
前室内分区

前端
static/contacts/index.html
的
app/main.py
app/routers/contacts.py
app/routers / init.py
app/crud.py
app/database.py
app/models.py
app/schemas.py
app / init.py
app/static/下的所有.py（用于静态资源托管或托管工具）
三、核心功能实现

实验室接口（以文件线索为概述职责）
app/main.py
创建FastAPI实例，挂载路由，配置启动项（如有）
可能包含静态资源托管：将根目录下的 static/ 为 /static
app/routers/contacts.py
相似相关的路由集合，通常包括：
GET /联系人：列表或查询
POST /联系人：新增
PUT /contacts/{id}：更新
DELETE /contacts/{id}：删除
app/schemas.py
Pydantic模型：如ContactIn、ContactOut、Pagination等
app/models.py
SQLAlchemy ORM实体：Contact 等
app/crud.py
数据访问封装：create_contact、get_contacts、update_contact、delete_contact…
app/database.py
数据库引擎与会话管理：create_engine/session/async_session 等（视实现而定）
前端页面（static/contacts/index.html）
静态 HTML 页面，通常通过 fetch 调用 /contacts 等 API
页面元素包括：外汇表单、列表、编辑/删除按钮等（如尚未实现，可占位作为页面）
四、开发过程中的问题与解决

CORS 跨域
症状：若直接file://打开index.html调域接口，浏览器报跨
解决建议：
在app/main.py中添加CORSMiddleware
或通过托管静态目录，从http://127.0.0.1:8000/static/contacts/index.html%E8%AE%BF%E9%97%AE
数据库初始化
症状：首次运行表不存在
解决建议：
在 app/database.py/main.py 中增加创建表逻辑（如 SQLAlchemy 的 Base.metadata.create_all）
或提供Alembic迁移（若项目未接入，可后续补充）
路由组织
建议：
在 app/main.py 中使用 app.include_router(contacts_router, prefix="/contacts", Tags=["contacts"])
统一使用 /api 外部（如 /api/contacts），彼此之间区分
五、项目运行与测试

启动
安装依赖：pip install -rrequirements.txt（若未提供，请导出）
运行：uvicorn app.main:app --reload
访问API文档：/docs 或 /redoc
访问前沿页面
方式A（推荐）：通过托管静态目录访问
http://127.0.0.1:8000/static/contacts/index.html
方式B：直接在文件系统打开index.html（可能会遇到CORS，需要按上节处理）
基础示例测试（可用HTTPie/Postman）
列表：http :8000/contacts
新增：http POST :8000/contacts name=Alice email= [e-mail]
更新：http PUT :8000/contacts/1 name=Alice2
删除：http DELETE :8000/contacts/1
六、总结

明确的边界：根目录 static/ 是前端；app/ 下的 .py 全部是设备
职责明确：路由器负责路由，schemas负责校验与序列化，模型映射数据表，crud聚合数据操作
易扩展：前端可以继续拆分CSS/JS；桌面可加鉴权、分页、搜索与统计
七、项目展示
1.运行成功展示

2.系统整体界面

3.功能演示
保存联系人：

删除联系人：

查找联系人：

八、感悟
做这个项目时，我总是把“先跑通、再反转”放在前面：用FastAPI搭起入口，路由器负责路由，模式做边界校验，模型与CRUD管数据库读写，数据库管连接与建表，结构声明后，CRUD和搜索很快成型；前置用static/contacts/index.html的后端HTML + fetch直连，借助托管静态资源与CORS配置，把跨域与路径问题一次性解决，端到端联调不止。数据层面同时做Pydantic校验与数据库唯一约束（如电子邮件），避免“漏网之鱼”；接口文档直接用/docs暴露，配合最小化就能快速回归。

工程取舍上，我刻意避免一开始就过度消耗，只保留必要的分层与时序命名（ContactCreate/Update/Out等），保证紧急、定位。README里统一启动命令（uvicorn app.main:app --reload）和访问入口（/docs与/static/contacts/index.html），让任何人拉下代码立即刻跑起来。等功能稳定后，再补分页与排序、统一返回体、鉴权，以及把SQLite平滑迁移到MySQL/PostgreSQL并引入Alembic/Docker，把这个“能用的小陶瓷”演化为“可维护的长期服务”。