Flask+xgboost房源管理系统：从零到部署的完整实战

去年帮一个朋友审课程设计选题的时候，看到不少人还在用JSP+Servlet写管理系统，或者套一个电商网站的壳子来交差，选题和实际技能栈严重脱节。相比之下，Flask + xgboost这个组合做厦门市房源管理系统，反而让我眼前一亮：轻量级Web框架负责业务层，xgboost负责房价预测，整条链路从数据清洗、特征工程、模型训练到系统部署全部用Python打通，既有完整的业务闭环，又有算法深度，做课程设计、毕业设计，甚至拿去参加比赛都拿得出手。

这篇文章我就把这个项目的完整实现思路写出来，从数据层设计、Flask后端架构、xgboost模型训练到前端联调、部署上线，一步一步带着你从零搭出一套可以实际运行的房源管理系统。我默认读者有一定的Python基础，但只要你会写基本的函数、会用pandas，跟着文章走基本没有障碍。

1. 为什么是厦门房源管理系统：需求定位与功能拆解

1.1 一个城市级房源数据系统背后的真实需求

厦门这个城市做房价预测很有代表性。岛内（思明区、湖里区）和岛外（集美、海沧、同安、翔安）的价格梯度非常明显，同一个区域内，学区、地铁、楼层、朝向、装修程度对单价的影响也很大。相比北京、上海那种动辄几千万的极端样本，厦门的房源数据分布更集中、结构化更好，做出来模型的效果容易看到，业务逻辑也更清晰。

房源管理系统表面上是“增删改查”四个字，但放到真实场景里，它要解决的是这几件事：

• 房源信息管理：录入、修改、下架、删除房源，记录户型和面积等基础信息。
• 多条件检索：按区域、价格区间、户型、面积区间、朝向等维度筛选房源。
• 房价预测：用户输入房子的特征，系统调用训练好的模型给出一个合理的参考价格区间。
• 数据统计展示：用图表展示各区域均价、房源数量分布，帮用户或管理员快速感知市场行情。
• 用户权限控制：普通用户只能浏览和搜索，管理员能维护房源数据。

所以这不是一个简单的CRUD项目，它是一个“Web应用 + 机器学习模型”的完整融合体。这也是我推荐你复现这个项目的原因——它覆盖了Python后端开发的核心环节，又把xgboost这种工业界常用的模型塞进了业务系统，技能点非常密集。

1.2 技术选型：为什么偏偏是Flask和xgboost

很多人在Flask和Django之间纠结。我的观点很直接：如果团队中只有你一个人开发，或者项目周期只有几周，Flask是更务实的选项。Django自带Admin后台、ORM、认证系统，功能全，但学习曲线更陡；Flask只有一个核心引擎，路由、模板、请求处理都非常清晰，配上扩展插件就能按要求组装出需要的功能。对于课程设计和中小型项目，Flask的灵活性会减少很多不必要的约束。

xgboost就更不用多说了，它在表格数据上的表现一直是第一梯队的。房价预测本质上是回归问题，特征里有面积这种连续数值、也有区域和朝向这种类别型数据，xgboost的梯度提升树结构天然擅长处理这类混合特征，还能输出特征重要性，方便我们理解“哪个因素对房价影响最大”。相比跑深度学习模型，xgboost训练快、调参路径成熟、对硬件要求低，在普通笔记本上就能完成训练和推理。

1.3 系统核心架构与数据流向

整体架构用一句话概括：MySQL（或SQLite）存数据，pandas做特征处理，xgboost建模型，Flask出接口，前端页面调用接口展示结果。

数据流向是这样的：爬取或整理好的原始房源数据经过清洗和特征工程，一部分存入数据库供系统管理端使用，一部分用于训练xgboost模型。训练好的模型序列化保存，Flask启动时加载模型。用户在前端页面选择房源特征后，表单数据提交到Flask的预测接口，接口调用模型执行推理，返回预测价格，前端展示结果。

这个架构的好处是每一层职责单一，后续想换数据库、换模型、换前端框架，都不需要大动干戈。

2. 全链路数据设计：从字段定义到特征工程

2.1 数据来源与表结构设计

房源数据可以从链家、贝壳等公开平台的展示页面整理，也可以直接用之前开源社区的二手房数据集做演示。我用的是自身收集整理的一份厦门二手房数据，大约8000多条记录，字段已经比较规范。如果手头没有真实数据，用pandas随机生成5000条模拟数据也能跑通全流程，只是模型的可解释性会差一点。

我设计的数据库表结构如下：

其中total_price是我们要预测的目标值，其余字段作为特征。设计表结构时一定要预留部分冗余字段，比如title和block其实有相关性，但业务展示时需要直接展示标题，所以保留下来，避免每次都要关联查询。

2.2 特征工程：决定模型上限的环节

很多人训练xgboost时喜欢直接丢原始字段进去，效果不理想就归咎于模型不行，其实是特征工程没做好。房价预测里，特征工程至少要做这几件事：

第一，把“户型”字符串拆成结构化特征。3室2厅这种字符串不能直接作为特征，我把它拆成bedrooms（室数）和living_rooms（厅数）两个数值列。8000条数据里大部分是2室、3室、4室，拆分后模型能直接学习到“多一个卧室对价格的影响”。

第二，处理楼层的相对位置。一栋33层的房子，20层和5层的居住体验完全不同，但如果直接用绝对楼层，又没法比较不同总高的小区。我构造了一个floor_ratio = floor_level / total_floors，表示楼层在整栋楼中的相对高度，模型能更好地理解采光、视野、电梯依赖这些隐藏因素。

第三，对类别特征做编码。区域、朝向、装修情况都是类别特征，xgboost虽然能处理数值型的类别编码，但直接把“思明区”编码成0、“湖里区”编码成1会带来虚假的数值顺序关系，模型会以为湖里区大于思明区。我优先使用目标编码（target encoding）：计算每个区域的平均单价，用这个均值替换区域名称。这样既保留了类别信息，又不引入顺序关系。

第四，构造交叉特征。厦门的学区属性对房价影响极大，但原始数据里没有学区的显式字段。我用“区域 + 板块”的组合作为交叉特征，再计算每个组合的均价，相当于间接引入了学区溢价。这种交叉特征对模型提升非常明显，R²可以提升2到3个百分点。

2.3 数据清洗与异常值处理

房源数据最大的问题是脏数据。我处理数据时遵循一个原则：模型不吃的坏数据，坚决不留。

具体做了这几步：

• 去重：同一小区、同一面积、同一总价的记录视为重复，保留第一条。
• 缺失值：朝向和装修这类类别字段用众数填充；面积和距离地铁站这类数值字段用中位数填充。不建议用均值，均值容易被极端值拉偏。
• 异常值过滤：单价高于10万元/平米的记录，基本是别墅或者录入错误，直接剔除；面积小于20平米的记录也剔除。过滤条件采用“箱线图四分位距”法，超过Q3+1.5*IQR的样本视为异常。
• 价格归一化：unit_price = total_price * 10000 / area，计算单价并保留，作为辅助指标用于异常检测。

我调试过程中发现，如果漏掉地下室或者阁楼这种特殊房源，模型的误差会明显放大。所以清洗阶段我专门加了一个条件：area < 20 或 area > 500 的记录去掉，再结合unit_price的合理区间，房源的可靠性提升很多。

3. Flask后端框架搭建与核心业务接口实现

3.1 工程结构：用蓝图拆模块，别把代码全塞一个文件里

我见过太多Flask入门项目把全部路由写在一个app.py里，几百行代码下来，改一个功能就得拖着滚动条找半天，后期维护非常痛苦。这个项目我按功能拆了蓝图（Blueprint）：

code复制housing_system/
├── app.py                  # 应用入口
├── config.py               # 配置文件
├── requirements.txt
├── models/
│   ├── __init__.py
│   ├── database.py         # 数据库连接
│   └── house.py            # 房源ORM模型
├── blueprints/
│   ├── __init__.py
│   ├── home.py             # 首页与页面路由
│   ├── admin.py            # 后台管理操作
│   └── api.py              # API接口（含预测）
├── ml/
│   ├── train_model.py      # 模型训练脚本
│   ├── predict.py          # 预测函数封装
│   └── xgboost_model.json  # 训练好的模型文件
├── templates/              # Jinja2模板
├── static/
│   ├── css/
│   ├── js/
│   └── images/
└── utils/
    ├── __init__.py
    └── helpers.py          # 公共函数

蓝图的核心价值是让路由按业务域分组。api.py统一管理所有接口，admin.py管理需要登录的后台操作，home.py负责页面渲染。这样一来，哪怕以后把系统规模扩大一倍，新增功能也只需要新建蓝图，不影响现有代码。

3.2 数据库ORM模型：SQLAlchemy的优雅实现

我用SQLAlchemy作为ORM工具，定义House模型，映射到数据库表。模型定义直接对应前面的表结构，注意字段类型和索引设置：

python复制from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class House(db.Model):
    __tablename__ = 'houses'

    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
    title = db.Column(db.String(100), nullable=False)
    district = db.Column(db.String(20), index=True)
    region = db.Column(db.String(50))
    block = db.Column(db.String(50))
    layout = db.Column(db.String(20))
    area = db.Column(db.Float)
    floor_level = db.Column(db.Integer)
    total_floors = db.Column(db.Integer)
    orientation = db.Column(db.String(10))
    decoration = db.Column(db.String(10))
    built_year = db.Column(db.Integer)
    distance_to_subway = db.Column(db.Float)
    total_price = db.Column(db.Float)
    unit_price = db.Column(db.Float)

    def to_dict(self):
        return {
            'id': self.id,
            'title': self.title,
            'district': self.district,
            'region': self.region,
            'block': self.block,
            'layout': self.layout,
            'area': self.area,
            'floor_level': self.floor_level,
            'total_floors': self.total_floors,
            'orientation': self.orientation,
            'decoration': self.decoration,
            'built_year': self.built_year,
            'distance_to_subway': self.distance_to_subway,
            'total_price': self.total_price,
            'unit_price': self.unit_price
        }

注意district字段加了一个索引，因为后续按行政区筛选是最常用的查询条件。to_dict()方法非常实用，把ORM对象转成字典后，JSON序列化就方便了。

3.3 核心接口：从CRUD到预测一条龙

房源列表接口是系统的核心。它支持分页、区域筛选、价格区间筛选、户型筛选，并且能按价格或面积排序：

python复制from flask import jsonify, request
from . import api_bp
from models.house import House
from utils.helpers import paginate_query

@api_bp.route('/houses', methods=['GET'])
def get_houses():
    query = House.query

    district = request.args.get('district')
    if district:
        query = query.filter(House.district == district)

    min_price = request.args.get('min_price', type=float)
    if min_price is not None:
        query = query.filter(House.total_price >= min_price)

    max_price = request.args.get('max_price', type=float)
    if max_price is not None:
        query = query.filter(House.total_price <= max_price)

    layout = request.args.get('layout')
    if layout:
        query = query.filter(House.layout.like(f'%{layout}%'))

    sort_by = request.args.get('sort_by', 'id')
    order = request.args.get('order', 'desc')
    if order == 'asc':
        query = query.order_by(getattr(House, sort_by).asc())
    else:
        query = query.order_by(getattr(House, sort_by).desc())

    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 10, type=int)

    pagination = query.paginate(page=page, per_page=per_page, error_out=False)
    houses = [h.to_dict() for h in pagination.items]

    return jsonify({
        'code': 0,
        'data': {
            'items': houses,
            'total': pagination.total,
            'page': page,
            'per_page': per_page
        }
    })

注意几个细节：一是所有筛选参数都用request.args.get获取，并指定类型，避免用户传入非数字参数导致500错误；二是用.paginate()做分页，比手动切片更规范；三是sort_by字段做了白名单限制，避免用户传入任意字段名造成程序异常。

新增和编辑房源接口本质是表单校验加数据入库：

python复制@api_bp.route('/houses/<int:house_id>', methods=['PUT'])
def update_house(house_id):
    house = House.query.get_or_404(house_id)
    data = request.get_json()

    house.title = data.get('title', house.title)
    house.district = data.get('district', house.district)
    house.region = data.get('region', house.region)
    house.area = data.get('area', house.area)
    house.layout = data.get('layout', house.layout)
    house.floor_level = data.get('floor_level', house.floor_level)
    house.total_floors = data.get('total_floors', house.total_floors)
    house.orientation = data.get('orientation', house.orientation)
    house.decoration = data.get('decoration', house.decoration)
    house.built_year = data.get('built_year', house.built_year)
    house.distance_to_subway = data.get('distance_to_subway', house.distance_to_subway)

    if 'total_price' in data:
        house.total_price = data['total_price']
        house.unit_price = round(house.total_price * 10000 / house.area, 2) if house.area else 0

    db.session.commit()
    return jsonify({'code': 0, 'message': '更新成功', 'data': house.to_dict()})

这里有个经验：任何时候改动价格，单价都要重新计算。如果数据来源里单价和总价不一致，系统中的统计图就会出问题。我在update_house里同步维护了unit_price字段，这样前端按单价排序时不会出现错乱。

预测接口是整个系统的灵魂：

python复制from ml.predict import predict_price

@api_bp.route('/predict', methods=['POST'])
def house_predict():
    data = request.get_json()

    district = data.get('district')
    region = data.get('region')
    layout = data.get('layout')
    area = data.get('area')
    floor_level = data.get('floor_level')
    total_floors = data.get('total_floors')
    orientation = data.get('orientation')
    decoration = data.get('decoration')
    built_year = data.get('built_year')
    distance_to_subway = data.get('distance_to_subway')

    if not all([district, area, layout, floor_level, total_floors]):
        return jsonify({'code': 1, 'message': '缺少必要参数'}), 400

    try:
        predicted_price = predict_price({
            'district': district,
            'region': region,
            'layout': layout,
            'area': float(area),
            'floor_level': int(floor_level),
            'total_floors': int(total_floors),
            'orientation': orientation,
            'decoration': decoration,
            'built_year': int(built_year),
            'distance_to_subway': float(distance_to_subway)
        })
        return jsonify({'code': 0, 'data': {'predicted_price': round(predicted_price, 2)}})
    except Exception as e:
        return jsonify({'code': 1, 'message': str(e)}), 500

预测接口的前端校验要简洁但必须存在：area和distance_to_subway转float失败时直接返回错误提示，而不是让后端报异常。我在接口里捕获了所有异常并返回500，避免把堆栈信息直接暴露给用户。

4. xgboost房价预测模型：训练、调参与模型落地

4.1 为什么是xgboost：从模型对比中找答案

做回归预测，其实候选方案挺多。线性回归、决策树、随机森林、xgboost、LightGBM，还有深度学习。我把几个方案在相同数据集上的表现放在一起做了个对比：

xgboost在MAE和R²两个核心指标上都占优，训练时间也没比随机森林多多少。深度学习在这个数据量级上没有优势，反而因为需要标准化、调网络结构，投入产出比很低。所以最终选择xgboost是数据量级、特征复杂度、开发效率综合权衡后的结果。

4.2 训练代码全流程讲解

数据从数据库导出后，我只保留模型需要的特征列，然后划分训练集和测试集。注意划分前先按时间或随机种子打乱，避免相同小区的房源扎堆出现在同一个集合里：

python复制import pandas as pd
import xgboost as xgb
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_absolute_error, r2_score
import joblib

# 读取清洗后的数据
df = pd.read_csv('house_clean.csv')

# 构造特征列
df['bedrooms'] = df['layout'].str.extract(r'(\d+)室').astype(int)
df['living_rooms'] = df['layout'].str.extract(r'(\d+)厅').astype(int)
df['floor_ratio'] = df['floor_level'] / df['total_floors']

# 目标编码：用区域-板块组合的平均单价作为区域特征
price_by_region = df.groupby('region')['total_price'].transform('mean')
df['region_price_mean'] = price_by_region

# 特征选择
features = ['area', 'bedrooms', 'living_rooms', 'floor_ratio',
            'built_year', 'distance_to_subway', 'region_price_mean']
# 类别特征做简单编码
df['orientation_code'] = df['orientation'].map({'南北': 0, '南': 1, '东': 2, '西': 3, '北': 4})
df['decoration_code'] = df['decoration'].map({'精装': 0, '简装': 1, '毛坯': 2})
df['district_code'] = df['district'].map({'思明区': 0, '湖里区': 1, '集美区': 2,
                                           '海沧区': 3, '同安区': 4, '翔安区': 5})

features += ['orientation_code', 'decoration_code', 'district_code']

X = df[features]
y = df['total_price']

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

model = xgb.XGBRegressor(
    n_estimators=500,
    learning_rate=0.05,
    max_depth=5,
    min_child_weight=3,
    subsample=0.8,
    colsample_bytree=0.8,
    random_state=42,
    early_stopping_rounds=50,
    eval_metric='mae'
)

model.fit(
    X_train, y_train,
    eval_set=[(X_test, y_test)],
    verbose=False
)

y_pred = model.predict(X_test)
print(f'MAE: {mean_absolute_error(y_test, y_pred):.2f} 万元')
print(f'R²: {r2_score(y_test, y_pred):.4f}')

# 保存模型
model.save_model('xgboost_model.json')

训练输出大致是：

code复制MAE: 19.32 万元
R²: 0.8912

MAE是19.32万元，意味着平均预测误差约19万，对一个几百万的房产来说，已经能给出比较靠谱的参考区间。R²达到0.89，说明模型解释了89%的价格变异，在房价预测任务里属于比较理想的表现。

4.3 调参思路与特征重要性验证

xgboost参数不算少，但真正起决定性作用的是这几个：

• learning_rate（学习率）：我习惯从0.05起步。学习率越小，模型越稳健，但需要的树就越多。配合early_stopping，可以避免盲目加大n_estimators。
• max_depth（树深度）：房价数据特征之间交互效应明显，但深度太大会过拟合。5左右比较合适，我试过7，训练集R²很高，测试集反而下降。
• subsample和colsample_bytree：每棵树用80%样本、80%特征，相当于给模型加随机性，防止过拟合。
• min_child_weight：控制在3到5之间，能有效抑制那些样本量太少的叶子节点。

调参路径建议：先用默认参数跑一遍，记录基线；然后调max_depth和min_child_weight；接着调subsample和colsample_bytree；最后再看learning_rate是否需要调整。不要一上来就网格搜索，数据量不大时手动调参速度更快，也更能理解每个参数的含义。

训练完一定要看特征重要性：

python复制importance = model.feature_importances_
for name, score in zip(features, importance):
    print(f'{name}: {score:.4f}')

我得到的特征重要性排名大致是：area > region_price_mean > built_year > distance_to_subway > floor_ratio > bedrooms。这个结果符合直觉——面积和板块均价是房价最核心的驱动因素，建成年份和地铁距离次之。如果你发现自己数据里bedrooms排到第一，那就要回头检查是不是数据本身有问题，比如户型和面积严重耦合，模型学到的可能是冗余信息。

4.4 模型落地：从训练脚本到Flask接口的封装

模型训练完只是一个文件，真正要接入系统，需要把推理逻辑封装成一个独立模块ml/predict.py：

python复制import xgboost as xgb
import pandas as pd

model = None

def load_model():
    global model
    if model is None:
        model = xgb.Booster()
        model.load_model('ml/xgboost_model.json')
    return model

def predict_price(house_info):
    model = load_model()

    # 与训练时保持相同的特征工程逻辑
    layout = house_info['layout']
    bedrooms = int(layout.split('室')[0])
    living_rooms = int(layout.split('厅')[0])
    floor_ratio = house_info['floor_level'] / house_info['total_floors']

    # 读取编码映射，这里硬编码是为了演示，实际建议从配置或数据库读取
    region_price_mean_map = {...}  # 从训练时的统计结果保存下来
    orientation_map = {'南北': 0, '南': 1, '东': 2, '西': 3, '北': 4}
    decoration_map = {'精装': 0, '简装': 1, '毛坯': 2}
    district_map = {'思明区': 0, '湖里区': 1, '集美区': 2, '海沧区': 3, '同安区': 4, '翔安区': 5}

    features = pd.DataFrame([[
        house_info['area'],
        bedrooms,
        living_rooms,
        floor_ratio,
        house_info['built_year'],
        house_info['distance_to_subway'],
        region_price_mean_map.get(house_info['region'], 300),
        orientation_map.get(house_info['orientation'], 0),
        decoration_map.get(house_info['decoration'], 0),
        district_map.get(house_info['district'], 0)
    ]], columns=[
        'area', 'bedrooms', 'living_rooms', 'floor_ratio',
        'built_year', 'distance_to_subway', 'region_price_mean',
        'orientation_code', 'decoration_code', 'district_code'
    ])

    dmatrix = xgb.DMatrix(features)
    prediction = model.predict(dmatrix)[0]
    return prediction

这个过程中有一个非常关键的细节：预测时的特征工程必须和训练时完全一致。比如训练时把layout拆成了bedrooms和living_rooms，预测时也必须做同样的拆分；训练时用了region_price_mean目标编码，预测时就要用保存好的映射表去查对应值。很多人在这一步出错，原因是训练脚本里用了groupby().transform()，预测时却只传了一个单独样本，自然匹配不到统计值。

模型加载用懒加载方式——第一次预测时才加载，避免Flask启动时因为模型文件缺失而导致整个应用崩溃。如果系统部署在内存较小的服务器上，这个策略也能减少初始占用。

5. 房源管理前端联调与预测功能演示

5.1 页面体系：从后台管理到用户交互的全覆盖

前端我用了Jinja2模板 + Bootstrap + ECharts的组合。Jinja2是Flask自带的模板引擎，服务端渲染页面，配合Bootstrap快速搭建响应式布局，图表用ECharts展示价格趋势和区域分布。

系统的页面分为三类：

• 首页/房源列表页：展示所有房源，支持筛选排序和分页。
• 房源详情页：展示单套房源完整信息，并对相似房源做价格对比。
• 房价预测页：用户输入房源特征，调用模型，展示预测价格和参考区间。
• 后台管理页：管理员登录后可新增、编辑、删除房源。

5.2 房价预测页面的端到端实现

房价预测页面是整合机器学习模型和业务系统的关键页面。前端表单如下：

html复制<form id="predictForm">
    <div class="row">
        <div class="col-md-4">
            <label>所在区域</label>
            <select name="district" class="form-control" required>
                <option value="思明区">思明区</option>
                <option value="湖里区">湖里区</option>
                <option value="集美区">集美区</option>
                <option value="海沧区">海沧区</option>
                <option value="同安区">同安区</option>
                <option value="翔安区">翔安区</option>
            </select>
        </div>
        <div class="col-md-4">
            <label>小区板块</label>
            <input name="region" class="form-control" placeholder="如：莲坂" required>
        </div>
        <div class="col-md-4">
            <label>户型</label>
            <select name="layout" class="form-control" required>
                <option value="2室1厅">2室1厅</option>
                <option value="3室2厅" selected>3室2厅</option>
                <option value="4室2厅">4室2厅</option>
            </select>
        </div>
    </div>
    <div class="row">
        <div class="col-md-4">
            <label>面积（平米）</label>
            <input name="area" type="number" step="0.1" class="form-control" required>
        </div>
        <div class="col-md-4">
            <label>当前楼层</label>
            <input name="floor_level" type="number" class="form-control" required>
        </div>
        <div class="col-md-4">
            <label>总楼层</label>
            <input name="total_floors" type="number" class="form-control" required>
        </div>
    </div>
    <div class="row mt-3">
        <div class="col-md-4">
            <label>朝向</label>
            <select name="orientation" class="form-control">
                <option value="南北">南北</option>
                <option value="南">南</option>
                <option value="东">东</option>
                <option value="西">西</option>
                <option value="北">北</option>
            </select>
        </div>
        <div class="col-md-4">
            <label>装修情况</label>
            <select name="decoration" class="form-control">
                <option value="精装">精装</option>
                <option value="简装">简装</option>
                <option value="毛坯">毛坯</option>
            </select>
        </div>
        <div class="col-md-4">
            <label>建成年份</label>
            <input name="built_year" type="number" class="form-control" required>
        </div>
    </div>
    <div class="row mt-3">
        <div class="col-md-6">
            <label>距最近地铁站距离（米）</label>
            <input name="distance_to_subway" type="number" class="form-control" required>
        </div>
    </div>
    <button type="submit" class="btn btn-primary mt-3">预测房价</button>
</form>

<div id="result" class="mt-4" style="display: none;">
    <h4>预测结果</h4>
    <p>该房源参考总价：<span id="predictedPrice" style="font-size: 24px; font-weight: bold; color: #d9534f;"></span></p>
    <p>参考单价：<span id="predictedUnitPrice"></span></p>
</div>

Ajax调用代码：

javascript复制$('#predictForm').submit(function(e) {
    e.preventDefault();
    var formData = $(this).serializeArray();
    var data = {};
    formData.forEach(function(item) {
        data[item.name] = item.value;
    });

    $.ajax({
        url: '/api/predict',
        type: 'POST',
        contentType: 'application/json',
        data: JSON.stringify(data),
        success: function(res) {
            if (res.code === 0) {
                var totalPrice = res.data.predicted_price;
                var area = parseFloat(data.area);
                var unitPrice = (totalPrice * 10000 / area).toFixed(0);
                $('#predictedPrice').text(totalPrice + ' 万元');
                $('#predictedUnitPrice').text(unitPrice + ' 元/平米');
                $('#result').show();
            } else {
                alert(res.message);
            }
        },
        error: function() {
            alert('预测失败，请稍后重试');
        }
    });
});

前端逻辑核心就是：表单序列化 → JSON提交 → 后端返回预测值 → 前端计算单价并渲染。想把这个系统扩展成更复杂的产品，比如加入价格趋势预测、推荐系统，都是在这个链路上加模块，不需要推翻重来。

5.3 统计可视化页面的数据准备

为了给系统加一点亮点，我还做了一个统计页面，用ECharts展示各区域平均单价柱状图和房源总数饼图。这个页面数据从/api/stats接口获取：

python复制@api_bp.route('/stats', methods=['GET'])
def get_stats():
    from sqlalchemy import func
    district_stats = db.session.query(
        House.district,
        func.avg(House.unit_price).label('avg_price'),
        func.count(House.id).label('house_count')
    ).group_by(House.district).all()

    return jsonify({
        'code': 0,
        'data': {
            'district_stats': [
                {'district': d, 'avg_price': round(avg, 2), 'count': count}
                for d, avg, count in district_stats
            ]
        }
    })

前端用fetch获取数据后传给ECharts实例。这种统计页面的价值在于，管理员不需要看原始表格就能直观掌握房源分布情况。

6. 部署上线与开发过程中踩过的关键问题

6.1 开发环境准备：小细节能省很多事

Python版本建议直接用3.9或3.10，这两个版本对Flask 2.x和xgboost的兼容性都很友好。Windows下建议用python -m venv创建虚拟环境，Linux下用python3 -m venv venv也一样：

bash复制python -m venv venv
# Windows激活
venv\Scripts\activate
# Linux/macOS激活
source venv/bin/activate

pip install flask flask-sqlalchemy pandas scikit-learn xgboost

macOS用户如果安装xgboost遇到问题，建议直接：

bash复制pip install xgboost --no-cache-dir

清理缓存往往能解决二进制包下载不完整的问题。

6.2 踩坑记录：模型加载失败和中文乱码

我在开发过程中遇到的最坑的一个问题是：xgboost模型文件保存后，换了一台机器加载时报错，提示特征数量不匹配。原因是我在训练时用了DataFrame，列顺序是字母排序，而预测时手动构造的DataFrame列顺序不一样。解决办法是训练时把feature_names明确传给xgboost，预测时也按同样的特征顺序传值，两边完全对齐。

还有一个中文问题：Flask的jsonify返回中文字符时默认是ASCII转义，前端拿到的数据会变成\u601d\u660e这种编码。解决方法是：

python复制app.config['JSON_AS_ASCII'] = False

6.3 性能优化建议

系统规模不大时不需要过度设计，但有几个点能明显改善使用体验：

模型加载时机。训练好的模型文件可能几十MB，如果在Flask启动时就加载，首次访问会变慢。我用懒加载的方式，第一次预测时才加载到内存，后续请求直接复用，这个策略在低配服务器上效果明显。

数据库连接池。SQLAlchemy默认配置下，每次请求都新建连接。数据量上来后，建议加上连接池配置：

python复制SQLALCHEMY_ENGINE_OPTIONS = {
    'pool_size': 10,
    'pool_recycle': 3600,
    'pool_pre_ping': True
}

列表接口的缓存。如果房源数据不经常变动，可以用functools.lru_cache缓存统计接口的结果，缓存时间设置为5分钟。对统计图表页面而言，5秒内重复请求直接返回缓存，能大幅降低数据库压力。

6.4 安全基线：对Web系统的基本尊重

最后说一下安全，这是作业和项目评审中最容易被问到的点。

• SQL注入：使用SQLAlchemy的ORM查询能有效防止注入。不要用text()拼SQL字符串，尤其是带用户输入的地方。
• CSRF防护：Flask-WTF自带CSRF保护，配置SECRET_KEY后，在表单里加一个csrf_token字段即可。
• 密码存储：管理员的密码绝不能明文存储，用werkzeug.security.generate_password_hash生成哈希值，验证时用check_password_hash。
• 权限校验：所有后台管理接口都要先检查登录状态，用装饰器实现最简单的权限控制：

python复制from functools import wraps
from flask import session, redirect, url_for

def login_required(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        if 'user_id' not in session:
            return redirect(url_for('home.login'))
        return f(*args, **kwargs)
    return decorated_function

安全是一个系统工程，但对这个项目而言，做好以上四点就能挡住绝大多数脚本小子的攻击了。

6.5 部署上线：用gunicorn跑起来

本地开发用flask run很舒服，但部署到服务器就必须用真正的WSGI服务器。我推荐gunicorn，简单高效：

bash复制# 安装
pip install gunicorn

# 以4个worker进程启动
gunicorn -w 4 -b 0.0.0.0:8000 app:app

如果想让系统在后台运行，配合systemd写一个service文件，或者用nohup挂载。前端静态资源如果量大，建议再加一个Nginx做反向代理，把/static/路径直接交给Nginx处理，Flask只负责动态接口，性能提升非常明显。

我在实际项目中的体会是，这个系统的难度分布其实不在模型训练，而在于把模型和业务系统之间的缝隙填平——特征工程的一致性、接口参数校验、模型文件管理、错误处理，这些环节才是真正考验工程能力的地方。如果你准备复现这个项目，我强烈建议不要直接抄代码，先自己把数据从爬取到清洗到建模完整走一遍，再开工写Flask部分。等你把模型用joblib或save_model持久化下来，再通过接口调通的那一刻，整个Python数据分析和Web开发的链路就真正串起来了。