---

我的第一个Python项目实战：基于FastAPI的旅游推荐官系统，小白也能看懂

前言

大家好！作为一名Python初学者，我终于完成了自己的第一个完整项目——旅游推荐官 (Travel Advisor)。这篇文章将记录我的开发全过程，分享项目架构、技术选型和核心功能实现，希望能给同样在学习Python的小伙伴们一些参考和启发！

项目背景

一直想做一个实用的Web应用，结合自己对旅游的热爱，决定开发一个旅游推荐系统。用户可以浏览热门景点、查看天气、收藏喜欢的目的地，还能通过AI对话获取旅游建议。

技术选型

经过调研，我选择了以下技术栈：

技术	用途
FastAPI	Python异步Web框架，性能优异，自动生成API文档
MySQL	关系型数据库，存储用户、城市、评论等数据
PyMySQL	Python连接MySQL的驱动
HTML + CSS + JS	前端页面开发
Dify AI	集成AI对话能力
wttr.in	免费天气API

选择FastAPI的原因很简单：它是目前Python生态中最流行的Web框架之一，自带Swagger文档，开发效率高，对新手非常友好！

项目架构

travel_advisor/
├── app/                    # 后端核心代码
│   ├── main.py            # 应用入口，路由注册
│   ├── config.py          # 配置文件（数据库、API配置）
│   ├── database.py        # 数据库连接（单例模式）
│   ├── models/            # 数据模型（Pydantic）
│   ├── routers/           # API路由层
│   └── services/          # 业务逻辑层
├── static/                # 前端静态文件
│   ├── index.html         # 首页
│   ├── css/style.css      # 样式文件
│   ├── js/                # JavaScript文件
│   └── ...                # 其他页面
└── init_db.py             # 数据库初始化脚本

采用了经典的三层架构：

• 路由层 (Routers)：处理HTTP请求和响应
• 服务层 (Services)：封装业务逻辑
• 数据层 (Models/Database)：数据模型和数据库操作

功能模块详解

1. 用户系统

实现了注册、登录、会话管理功能：

@router.post("/api/register")
def register(request: UserRegister):
    if request.password != request.confirm_password:
        raise HTTPException(status_code=400, detail="两次密码不一致")
    # ...注册逻辑

@router.post("/api/login")
def login(req: Request, request: UserLogin):
    user = UserService.login(request.username, request.password)
    if user:
        req.session["user_id"] = user['id']
        req.session["username"] = user['username']
        # ...登录成功

使用了 SessionMiddleware 管理用户会话，确保登录状态持久化。

2. 城市与景点浏览

每个城市包含：名称、简介、图片、最佳旅游月份、标签等信息：

@router.get("/api/city/{name}")
def get_city(req: Request, name: str):
    city = CityService.get_city_by_name(name)
    comments = CommentService.get_city_comments(name)
    # ...返回城市详情、评论、推荐状态

数据初始化脚本预置了 20个热门旅游城市、30个代表性景点，从北京故宫到三亚亚龙湾，覆盖全国！

3. 推荐与排行榜

用户可以对喜欢的景点进行推荐，系统自动生成排行榜：

@router.get("/api/rankings")
def get_rankings():
    cities = CityService.get_all_cities()  # 按推荐数降序排列
    return {"success": True, "data": cities}

4. 收藏功能

用户可以收藏心仪的旅游目的地，方便日后查看：

@router.post("/api/favorite")
def favorite(request: FavoriteRequest):
    if request.cancel:
        FavoriteService.remove_favorite(request.username, request.city)
    else:
        FavoriteService.add_favorite(request.username, request.city)

5. 景点建议与审核

用户可建议新增景点，管理员审核后上线。这个功能实现了完整的 用户提交 -> 管理员审核 -> 上线 流程：

@router.post("/api/suggest-city")
def suggest_city(data: dict):
    # ...用户提交建议

@router.post("/api/admin/approve-suggestion")
def approve_suggestion(data: dict):
    # ...管理员审核通过

6. AI智能对话

集成 Dify AI 平台，实现旅游智能问答：

class ChatService:
    @staticmethod
    def chat(message):
        headers = {"Authorization": f"Bearer {DIFY_API_KEY}"}
        data = {"query": message, "response_mode": "blocking"}
        response = requests.post(DIFY_API_URL, headers=headers, json=data)
        # ...返回AI回答

7. 天气查询

调用 wttr.in 免费API，获取实时天气和3天预报：

def get_weather(city_name):
    url = f"https://wttr.in/{city_name}?format=j1"
    response = requests.get(url, timeout=10)
    # ...解析天气数据

8. 管理员后台

管理员可以管理城市信息（增删改查）、审核用户建议，实现完整的内容管理：

@router.post("/api/admin/add-city")
@router.post("/api/admin/update-city")
@router.post("/api/admin/delete-city")
@router.post("/api/admin/approve-suggestion")

数据库设计

项目使用MySQL数据库，共设计6张表：

users              - 用户表（用户名、密码、角色）
cities             - 城市表（名称、介绍、图片、标签等）
recommendations    - 推荐记录表（用户-城市关联）
favorites          - 收藏记录表（用户-城市关联）
city_suggestions   - 建议表（用户提交的新景点建议）
recommend_comments - 评论表（用户对景点的评价）

数据库连接采用单例模式，确保全局只有一个连接实例：

class Database:
    _instance = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super(Database, cls).__new__(cls)
            cls._instance._connection = None
        return cls._instance

项目亮点

1. 功能完整：从用户系统到内容管理，从推荐收藏到AI对话，功能覆盖全面
2. 架构清晰：采用三层架构，代码组织规范，易于扩展
3. 数据丰富：预置了30个国内热门景点数据，开箱即用
4. AI赋能：集成AI对话能力，提升用户体验
5. 易于部署：依赖简单，配置清晰

部署与运行

环境要求

• Python 3.9+
• MySQL 5.7+
• pip

运行步骤

# 1. 初始化数据库
python init_db.py

# 2. 安装依赖
pip install fastapi pymysql uvicorn requests

# 3. 启动服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 4. 访问
# 首页：http://localhost:8000/static/index.html
# API文档：http://localhost:8000/docs

默认账号

用户名	密码	角色
admin	admin	管理员
user1	password	普通用户
user2	password	普通用户

踩坑记录

作为新手，开发过程中也遇到了一些问题：

1. 跨域问题：前端页面访问API时遇到CORS错误，通过添加CORSMiddleware解决
2. 会话管理：一开始用JWT后来改为SessionMiddleware，对新手更友好
3. 数据库编码：中文存储出现乱码，设置charset='utf8mb4’后解决
4. 静态文件缓存：页面修改后浏览器缓存不更新，添加NoCacheMiddleware解决

总结

通过这个项目，我深入实践了：

• FastAPI框架的使用和API设计
• MySQL数据库的设计与操作
• 前后端分离的开发模式
• 第三方API的集成调用
• AI能力的接入

从零到一完成一个完整的Web应用，这段经历让我对Python Web开发有了更深刻的理解。项目的代码还有很多可以优化的地方，但作为第一个项目，它已经给了我极大的信心！

如果你也在学习Python，不妨动手做一个属于自己的项目，哪怕很小，完整的开发流程会让你收获满满！

完整的项目代码可以在我的Gitee仓库中找到，欢迎star和交流！

---

PI框架的使用和API设计

• MySQL数据库的设计与操作
• 前后端分离的开发模式
• 第三方API的集成调用
• AI能力的接入

从零到一完成一个完整的Web应用，这段经历让我对Python Web开发有了更深刻的理解。项目的代码还有很多可以优化的地方，但作为第一个项目，它已经给了我极大的信心！

如果你也在学习Python，不妨动手做一个属于自己的项目，哪怕很小，完整的开发流程会让你收获满满！

完整的项目代码可以在我的Gitee仓库中找到，欢迎私信我拿取仓库链接！

---

本文为我的第一个项目实战记录，希望能帮助到同样在路上的你！