簡(jiǎn)介這是一份基于DjangoMySQL實(shí)現(xiàn)的城市PM2.5空氣質(zhì)量數(shù)據(jù)可視化分析項(xiàng)目源碼適合Python初學(xué)者、Web開發(fā)學(xué)習(xí)者及數(shù)據(jù)分析愛好者參考使用。項(xiàng)目整合了宏觀空氣質(zhì)量數(shù)據(jù)的采集入庫、查詢統(tǒng)計(jì)與可視化展示全流程可幫助理解Django框架的MTV架構(gòu)、ORM數(shù)據(jù)庫操作以及前后端數(shù)據(jù)交互方式。壓縮包共66個(gè)文件約12.38MB包含17個(gè)Python源碼文件、24個(gè)CSV數(shù)據(jù)文件、4個(gè)XML配置、3個(gè)HTML模板、SQL數(shù)據(jù)庫腳本及部署文檔等。CSV數(shù)據(jù)覆蓋北上廣成沈等多座城市六年間PM2.5濃度變化以及PM2.5與溫度、濕度、大氣壓、風(fēng)向、露點(diǎn)等環(huán)境因素的關(guān)系數(shù)據(jù)SQL腳本與Django配置可直接還原數(shù)據(jù)庫表結(jié)構(gòu)。代碼按項(xiàng)目目錄、數(shù)據(jù)目錄、模板目錄組織結(jié)構(gòu)清晰。資源當(dāng)前已有145人學(xué)習(xí)下載。隨包附部署文檔、requirements依賴清單及README替換本地?cái)?shù)據(jù)即可直接運(yùn)行。通過源碼可掌握數(shù)據(jù)預(yù)處理、MySQL讀寫、圖表可視化等關(guān)鍵環(huán)節(jié)適合畢業(yè)設(shè)計(jì)或課程項(xiàng)目二次開發(fā)。1. 這套 DjangoMySQL 的 PM2.5 可視化項(xiàng)目到底能拿來做什么如果你手里有一份城市空氣質(zhì)量監(jiān)測(cè)的 CSV 數(shù)據(jù)想把它變成能在瀏覽器里交互查看的趨勢(shì)圖、小時(shí)對(duì)比圖、污染排行最直接的路徑就是 Django 做后端、MySQL 存數(shù)據(jù)、ECharts 出圖表。這個(gè)方向的項(xiàng)目在 Python 求職作品集里出現(xiàn)頻率極高核心價(jià)值在于它覆蓋了從數(shù)據(jù)清洗、關(guān)系建模到 Web 接口和前端渲染的完整鏈路不是那種只調(diào)個(gè)庫就出圖的玩具。適合的人群很明確剛學(xué)完 Django 基礎(chǔ)但不知道怎么寫第一個(gè)像樣項(xiàng)目的人想給簡(jiǎn)歷補(bǔ)一個(gè)有數(shù)據(jù)庫、有部署文檔的完整案例的轉(zhuǎn)行者以及需要快速搭建內(nèi)部空氣質(zhì)量看板的運(yùn)維或環(huán)境相關(guān)從業(yè)者。本文按實(shí)際落地順序把模型設(shè)計(jì)、數(shù)據(jù)導(dǎo)入、聚合查詢、圖表對(duì)接和部署驗(yàn)證逐個(gè)拆開講你會(huì)看到每個(gè)環(huán)節(jié)的參數(shù)設(shè)置和翻車點(diǎn)。2. 把數(shù)據(jù)落進(jìn) MySQLDjango 模型設(shè)計(jì)與環(huán)境準(zhǔn)備2.1 先定表結(jié)構(gòu)監(jiān)測(cè)記錄、監(jiān)測(cè)站點(diǎn)、污染物維度拿到 PM2.5 數(shù)據(jù)后第一件事不是寫視圖而是想清楚表和表之間的關(guān)系。大多數(shù)公開數(shù)據(jù)集長這樣每一行是一條監(jiān)測(cè)記錄包含站點(diǎn)名、時(shí)間、PM2.5 濃度、PM10、SO2、NO2、CO、O3。如果把全部字段塞進(jìn)一張表后續(xù)按站點(diǎn)、按天做統(tǒng)計(jì)時(shí)會(huì)反復(fù)出現(xiàn)冗余和慢查詢。常見做法是拆成三張表監(jiān)測(cè)站點(diǎn)表存站點(diǎn)名稱和經(jīng)緯度污染物維度表存污染物代碼和名稱監(jiān)測(cè)事實(shí)表存時(shí)間和各污染物數(shù)值。Django 里對(duì)應(yīng)的模型可以這樣寫from django.db import models class Station(models.Model): name models.CharField(max_length64, uniqueTrue, verbose_name站點(diǎn)名稱) longitude models.FloatField(verbose_name經(jīng)度) latitude models.FloatField(verbose_name緯度) city models.CharField(max_length32, verbose_name所屬城市) class Meta: db_table station class Pollutant(models.Model): code models.CharField(max_length16, uniqueTrue, verbose_name污染物代碼) name models.CharField(max_length32, verbose_name污染物名稱) class Meta: db_table pollutant class AirQualityRecord(models.Model): station models.ForeignKey(Station, on_deletemodels.CASCADE, verbose_name站點(diǎn)) pollutant models.ForeignKey(Pollutant, on_deletemodels.CASCADE, verbose_name污染物) record_time models.DateTimeField(verbose_name監(jiān)測(cè)時(shí)間) value models.FloatField(verbose_name濃度值) unit models.CharField(max_length16, defaultug/m3, verbose_name單位) class Meta: db_table air_quality_record indexes [ models.Index(fields[record_time, station], nameidx_time_station), ]這里最關(guān)鍵的決定是把每種污染物拆成獨(dú)立的記錄行而不是把 PM2.5、PM10 作為字段并列。原因有兩個(gè)一是數(shù)據(jù)導(dǎo)入時(shí) CSV 里列的順序經(jīng)常變化拆成行就不會(huì)被表結(jié)構(gòu)綁死二是后續(xù)做某一天各污染物對(duì)比只需要按時(shí)間和站點(diǎn)過濾SQL 寫起來清爽。如果你拿到的是已經(jīng)清洗好的一行一條記錄的數(shù)據(jù)那直接用這個(gè)模型。表名通過db_table指定避免 Django 默認(rèn)生成的appname_modelname式名字在部署遷移時(shí)引起混淆。idx_time_station聯(lián)合索引是為后面高頻的某一時(shí)間范圍 某個(gè)站點(diǎn)查詢準(zhǔn)備的實(shí)測(cè)在百萬行數(shù)據(jù)量下不加這個(gè)索引查詢耗時(shí)能從秒級(jí)降到毫秒級(jí)。2.2 數(shù)據(jù)導(dǎo)入腳本用 bulk_create 而不是循環(huán) insertCSV 數(shù)據(jù)導(dǎo)庫是第一個(gè)分水嶺。很多新手用for row in reader: Model.objects.create(...)數(shù)據(jù)量幾千行時(shí)還能忍幾萬行時(shí)直接卡到懷疑人生。正確做法是把解析和入庫分開用bulk_create批量寫入。import csv from datetime import datetime from django.utils.timezone import make_aware from .models import Station, Pollutant, AirQualityRecord def import_csv(file_path): station_cache {} pollutant_cache {} with open(file_path, encodingutf-8-sig) as f: reader csv.DictReader(f) batch [] batch_size 2000 for row in reader: station_name row[station] if station_name not in station_cache: station, _ Station.objects.get_or_create( namestation_name, defaults{longitude: float(row[lon]), latitude: float(row[lat]), city: row.get(city, )} ) station_cache[station_name] station for code in [pm25, pm10, so2, no2, co, o3]: val row.get(code) if val in (None, , NA): continue if code not in pollutant_cache: pollutant, _ Pollutant.objects.get_or_create(codecode) pollutant_cache[code] pollutant record_time make_aware(datetime.strptime(row[time], %Y-%m-%d %H:%M:%S)) batch.append(AirQualityRecord( stationstation_cache[station_name], pollutantpollutant_cache[code], record_timerecord_time, valuefloat(val), )) if len(batch) batch_size: AirQualityRecord.objects.bulk_create(batch, batch_sizebatch_size) batch.clear() if batch: AirQualityRecord.objects.bulk_create(batch, batch_sizebatch_size)這段腳本里有兩個(gè)容易被忽略的點(diǎn)encodingutf-8-sig是因?yàn)楹芏?CSV 文件從 Excel 導(dǎo)出來時(shí)帶 BOM 頭用普通utf-8讀會(huì)把\ufeff帶進(jìn)第一個(gè)列名導(dǎo)致解析失敗get_or_create配合本地緩存是為了避免每行都查一次數(shù)據(jù)庫站點(diǎn)表和污染物表的記錄數(shù)是有限的查一次存進(jìn) dict 后面直接用就行。make_aware是把 naive 的 datetime 變成帶時(shí)區(qū)的對(duì)象Django 的USE_TZTrue時(shí)會(huì)強(qiáng)制要求 aware datetime否則寫入報(bào)錯(cuò)。實(shí)測(cè)下來10 萬行原始記錄約 60 萬條事實(shí)記錄用bulk_create寫入 MySQL 大約需要 20 到 40 秒如果你仍然逐條 create同樣的數(shù)據(jù)可能要跑十幾分鐘而且中間任何一條失敗都得重來。2.3 settings 里 MySQL 的 4 個(gè)必配參數(shù)與編碼坑Django 默認(rèn)連 SQLite切換到 MySQL 需要裝驅(qū)動(dòng)并在 settings 里改一段配置。常見驅(qū)動(dòng)有mysqlclient和pymysql我的建議是直接用pymysql因?yàn)樗惭b不需要編譯本地 C 擴(kuò)展Windows 和 Linux 上都不容易踩坑。import pymysql pymysql.install_as_MySQLdb() DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: air_quality_db, USER: root, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, CONN_MAX_AGE: 60, OPTIONS: { charset: utf8mb4, init_command: SET sql_modeSTRICT_TRANS_TABLES, }, } }四個(gè)必配參數(shù)CONN_MAX_AGE設(shè)為 60表示一個(gè)連接在一分鐘內(nèi)可復(fù)用避免每次請(qǐng)求都重新握手charset必須配utf8mb4不是utf8因?yàn)閡tf8在 MySQL 里最多支持 3 字節(jié)編碼存不了特殊字符和生僻字init_command里的sql_mode設(shè)置讓 MySQL 在寫入超長字段時(shí)拋異常而不是靜默截?cái)噙@個(gè)直接影響數(shù)據(jù)完整性HOST寫127.0.0.1而不是localhost有些系統(tǒng)上 localhost 會(huì)被解析成 socket 文件Django 連不上。另外創(chuàng)建數(shù)據(jù)庫時(shí)就要指定字符集這一步很多人忘記導(dǎo)致后面遷移建表全是 latin1 編碼中文亂碼滿屏飛。命令行里這樣建庫mysql -u root -p -e CREATE DATABASE air_quality_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;然后執(zhí)行python manage.py makemigrations和python manage.py migrate。如果遷移時(shí)報(bào)django.db.utils.OperationalError: (1130, Host ... is not allowed to connect)說明 MySQL 沒開遠(yuǎn)程權(quán)限在 MySQL 里執(zhí)行GRANT ALL PRIVILEGES ON air_quality_db.* TO root% IDENTIFIED BY 密碼; FLUSH PRIVILEGES;就能解決。運(yùn)行起來后確認(rèn)一下數(shù)據(jù)是否真的進(jìn)去了用SELECT COUNT(*) FROM air_quality_record;對(duì)數(shù)量然后抽查一條記錄看record_time和value是否為預(yù)期值。數(shù)據(jù)入庫這步做得越扎實(shí)后面可視化接口翻車的概率越低。3. 可視化接口背后的查詢邏輯聚合、分組與時(shí)間粒度3.1 按小時(shí)/天/月聚合的 ORM 寫法與對(duì)應(yīng) SQL前端圖表要展示的通常不是原始記錄而是聚合后的趨勢(shì)線。按天算日均 PM2.5、按月算月均、按小時(shí)看污染突變這些需求都對(duì)應(yīng) SQL 里的GROUP BY加時(shí)間函數(shù)。Django ORM 里做這件事用annotate但時(shí)間的截?cái)嘈枰柚鶷runc系列表達(dá)式。from django.db.models import Avg, F from django.db.models.functions import TruncDay, TruncHour from .models import AirQualityRecord def daily_average(station_id, start_date, end_date): rows ( AirQualityRecord.objects .filter( station_idstation_id, pollutant__codepm25, record_time__date__gtestart_date, record_time__date__lteend_date, ) .annotate(dayTruncDay(record_time)) .values(day) .annotate(avg_valueAvg(value)) .order_by(day) ) return list(rows)這段代碼生成的 SQL 大致是SELECT DATE(record_time) AS day, AVG(value) AS avg_value FROM air_quality_record WHERE station_id 1 AND pollutant_id 2 AND DATE(record_time) BETWEEN 2025-01-01 AND 2025-01-31 GROUP BY DATE(record_time) ORDER BY day;TruncDay(record_time)的作用是把 datetime 截?cái)嗟教煜喈?dāng)于 MySQL 里的DATE()函數(shù)換成TruncHour就是按小時(shí)分組。這里有一個(gè)性能細(xì)節(jié)record_time__date__gte會(huì)隱式地對(duì)record_time調(diào)用DATE()函數(shù)導(dǎo)致索引失效數(shù)據(jù)量大時(shí)全表掃描。正確寫法是直接用record_time__gtedatetime(2025,1,1)配合record_time__ltdatetime(2025,2,1)讓范圍過濾直接命中前面建的聯(lián)合索引。這個(gè)差別在百萬行數(shù)據(jù)上是 0.1 秒和 3 秒的區(qū)別。values(day)和annotate(avg_valueAvg(value))的順序是有講究的先values指定分組字段再annotate聚合Django 才會(huì)按day分組如果反過來聚合結(jié)果就不是你想要的分組粒度。這個(gè)順序錯(cuò)了不會(huì)報(bào)錯(cuò)但返回的數(shù)據(jù)會(huì)讓人摸不著頭腦是常見的隱蔽 bug。3.2 城市對(duì)比與均值計(jì)算annotate values 的組合除了單站點(diǎn)趨勢(shì)PM2.5 項(xiàng)目里最常見的還有城市維度對(duì)比比如同一天北京、上海、廣州的 PM2.5 均值分別是多少做成柱狀圖拍出污染排行。這需要跨站點(diǎn)點(diǎn)按城市分組如果你的站點(diǎn)表里已經(jīng)存了city字段Django 的 ORM 可以順著外鍵直接分組。from django.db.models import Avg from django.db.models.functions import TruncDay from .models import AirQualityRecord def city_daily_average(date): rows ( AirQualityRecord.objects .filter(record_time__datedate, pollutant__codepm25) .values(station__city, record_time__date) # 先分組再聚合 .annotate(city_avgAvg(value)) .order_by(-city_avg) ) return rows注意這里values(station__city, record_time__date)里用了跨表字段station__cityDjango 會(huì)自動(dòng)做 JOIN。如果Pollutant表里的 code 有唯一索引這里過濾pollutant__codepm25會(huì)比先查出污染物 ID 再過濾更快。實(shí)際執(zhí)行時(shí)可以用connection.queries查看 ORM 生成的 SQL 來驗(yàn)證如果看到 JOIN 了兩張不相關(guān)的表說明模型關(guān)系的related_name設(shè)置有問題。有時(shí)候現(xiàn)實(shí)需求是對(duì)比一組城市某時(shí)間段的達(dá)標(biāo)率而不是均值這在 SQL 里就是AVG(CASE WHEN value 75 THEN 1 ELSE 0 END)ORM 中用Avg(Case(When(value__lt75, then1.0), default0.0))實(shí)現(xiàn)。PM2.5 的 24 小時(shí)均值限值是 75 微克/立方米達(dá)標(biāo)率數(shù)據(jù)在可視化看板里比絕對(duì)值更有說服力。3.3 查詢性能索引設(shè)計(jì)與大表分頁數(shù)據(jù)量上了幾十萬行后接口響應(yīng)變慢幾乎都是索引問題。Django 的模型定義里已經(jīng)加了record_time station的聯(lián)合索引但如果你頻繁按污染物和時(shí)間過濾這個(gè)索引的字段順序需要重新考量。MySQL 索引遵循最左前綴原則查詢條件里如果只給pollutant_id和record_time聯(lián)合索引(record_time, station)就用不上。常見做法是把索引拆成兩個(gè)(pollutant_id, record_time)和(station_id, record_time)分別應(yīng)對(duì)某污染物全站點(diǎn)時(shí)序和某站點(diǎn)全污染物時(shí)序兩類高頻查詢。class Meta: db_table air_quality_record indexes [ models.Index(fields[pollutant, record_time], nameidx_pollutant_time), models.Index(fields[station, record_time], nameidx_station_time), ]加了索引后別忘了跑一下EXPLAIN驗(yàn)證EXPLAIN SELECT station_id, AVG(value) FROM air_quality_record WHERE pollutant_id 2 AND record_time BETWEEN 2025-01-01 AND 2025-01-31 GROUP BY station_id;看到type是range、key是idx_pollutant_time就說明索引生效了。如果還是ALL全表掃描檢查字段類型是否不一致——station_id是 int 而查詢里傳了字符串MySQL 會(huì)做隱式類型轉(zhuǎn)換然后放棄索引。另一個(gè)坑是圖表接口返回的數(shù)據(jù)量。如果你做的是整年逐小時(shí)曲線一年有 8760 個(gè)點(diǎn)一次性全返回會(huì)讓前端渲染卡死。常見的解法不是分頁圖表不適合頁碼翻動(dòng)而是后端限制采樣點(diǎn)數(shù)量。我的做法是超過 2000 個(gè)點(diǎn)時(shí)自動(dòng)把時(shí)間粒度從小時(shí)升到按天聚合這個(gè)邏輯放在視圖層判斷def trend_data(request, station_id): start request.GET.get(start) end request.GET.get(end) points AirQualityRecord.objects.filter( station_idstation_id, record_time__range(start, end) ).count() if points 2000: granularity day else: granularity hour # 按 granularity 走不同聚合分支接口層做一次粗粒度計(jì)數(shù)通常很快用COUNT(*)配合索引命中幾乎無感。用戶看到的圖表永遠(yuǎn)有數(shù)據(jù)只是縮放范圍大時(shí)顯示日線、小時(shí)范圍時(shí)顯示小時(shí)線體驗(yàn)上比轉(zhuǎn)圈圈等加載好很多。4. 把查詢結(jié)果渲染成圖表ECharts 的 JSON 對(duì)接方案4.1 返回 JSON 的視圖函數(shù)時(shí)間序列格式是關(guān)鍵Django 后端和 ECharts 前端的數(shù)據(jù)交接痛點(diǎn)從來不是怎么渲染圖形而是 JSON 格式的約定。ECharts 的折線圖需要 x 軸數(shù)據(jù)和 y 軸數(shù)據(jù)熱力圖需要三維數(shù)組儀表盤只需要一個(gè)數(shù)值。后端視圖的核心職責(zé)就是把聚合結(jié)果整理成 ECharts 能直接消費(fèi)的結(jié)構(gòu)。import json from django.http import JsonResponse from django.views.decorators.http import require_GET from django.utils.dateparse import parse_datetime from .query import daily_average require_GET def api_daily_trend(request): station_id request.GET.get(station_id) start parse_datetime(request.GET.get(start)) end parse_datetime(request.GET.get(end)) if not all([station_id, start, end]): return JsonResponse({code: 400, msg: 缺少 station_id/start/end 參數(shù)}, status400) rows daily_average(station_id, start, end) result { code: 0, data: { dates: [r[day].strftime(%Y-%m-%d) for r in rows], values: [round(r[avg_value], 1) for r in rows], unit: ug/m3, } } return JsonResponse(result)這個(gè)接口把日期格式化成了%Y-%m-%d字符串再放進(jìn) JSON。不要直接把 datetime 對(duì)象交給json.dumpsDjango 的JsonResponse遇到 datetime 會(huì)報(bào)TypeError: Object of type datetime is not JSON serializable到時(shí)候你還得返工加 default 參數(shù)不如一開始就格式化。require_GET裝飾器限制了這個(gè)接口不接受 POST因?yàn)椴樵冾惤涌诒举|(zhì)上沒有副作用。前端如果拿不到數(shù)據(jù)第一件事是看瀏覽器 Network 面板確認(rèn)請(qǐng)求是否真的發(fā)出去了以及響應(yīng)的code是不是 0。狀態(tài)碼 200 但業(yè)務(wù)碼 400 的情況在這類項(xiàng)目里很常見后端和前端對(duì)異常的定義一致是順利聯(lián)調(diào)的前提。4.2 折線圖、熱力圖、儀表盤的 ECharts 配置參數(shù)拿到 JSON 數(shù)據(jù)后ECharts 的配置就是照著官方示例改。折線圖展示日均 PM2.5 趨勢(shì)xAxis的type建議用category配合字符串日期不要用time類型再傳時(shí)間戳因?yàn)?category 在數(shù)據(jù)點(diǎn)不多時(shí)縮放更順滑也不用管時(shí)區(qū)。div idchart stylewidth: 100%; height: 420px;/div script fetch(/api/daily_trend?station_id1start2025-01-01end2025-01-31) .then(res res.json()) .then(res { if (res.code ! 0) return; const chart echarts.init(document.getElementById(chart)); chart.setOption({ title: { text: PM2.5 日均濃度 }, tooltip: { trigger: axis }, grid: { left: 60, right: 30, top: 40, bottom: 40 }, xAxis: { type: category, data: res.data.dates }, yAxis: { type: value, name: res.data.unit, splitLine: { lineStyle: { type: dashed } } }, series: [{ type: line, data: res.data.values, smooth: true, areaStyle: { opacity: 0.2 }, markLine: { silent: true, data: [{ yAxis: 75 }] } }] }); window.addEventListener(resize, () chart.resize()); }); /scriptmarkLine在 y 軸 75 處畫一條警戒線這是 PM2.5 日均濃度國家二級(jí)標(biāo)準(zhǔn)的限值有這條線用戶一眼就能看出哪些日期超標(biāo)了。areaStyle的透明度調(diào)到 0.2 會(huì)讓曲線下方有淡色填充視覺上更直觀。別忘了window.addEventListener(resize, () chart.resize())否則刷新瀏覽器窗口時(shí)圖表會(huì)溢出容器。如果需要做小時(shí)級(jí)熱力圖橫軸是 24 小時(shí)縱軸是日期顏色深度代表濃度ECharts 用visualMap分段顏色option { tooltip: {}, grid: { left: 80 }, xAxis: { type: category, data: hours }, // [00:00, 01:00, ...] yAxis: { type: category, data: days }, // [2025-01-01, ...] visualMap: { min: 0, max: 200, calculable: true, inRange: { color: [#dcebff, #8ec8ff, #ffd666, #ff7875] } }, series: [{ type: heatmap, data: data3d, // [[dateIndex, hourIndex, value], ...] label: { show: false } }] };熱力圖的數(shù)據(jù)格式是三維數(shù)組[dayIndex, hourIndex, value]不是平鋪的數(shù)值列表后端接口要按索引組裝。這種圖適合展示某站點(diǎn)一周里每個(gè)小時(shí)污染濃度分布能看出早晚高峰的規(guī)律性波動(dòng)。4.3 定時(shí)刷新與后端緩存讓頁面不卡死PM2.5 數(shù)據(jù)的更新頻率通常是小時(shí)級(jí)但用戶不會(huì)手動(dòng)刷新頁面前端做個(gè) 30 分鐘自動(dòng)請(qǐng)求是常規(guī)操作。定時(shí)拉取的實(shí)現(xiàn)簡(jiǎn)單但要注意兩個(gè)問題一是用戶切換了站點(diǎn)或時(shí)間范圍之后要重置計(jì)時(shí)器二是如果每次拉取都打全量接口MySQL 撐不住高并發(fā)訪問。解決方案是給查詢接口加一層文件緩存或內(nèi)存緩存。數(shù)據(jù)的時(shí)間跨度決定了它的語義——對(duì)于已經(jīng)過去的日期聚合結(jié)果是不會(huì)變的可以放心緩存只有今天的數(shù)據(jù)會(huì)隨著新的監(jiān)測(cè)記錄寫入而變化from django.core.cache import cache def api_daily_trend(request): station_id request.GET.get(station_id) start request.GET.get(start) end request.GET.get(end) cache_key fdaily_trend_{station_id}_{start}_{end} result cache.get(cache_key) if result is None: rows daily_average(station_id, parse_datetime(start), parse_datetime(end)) # ... 組裝 result cache.set(cache_key, result, timeout1800) # 半小時(shí)過期 return JsonResponse(result)cache.set的 timeout 設(shè)成 1800 秒正好和前端 30 分鐘定時(shí)刷新同步緩存還是熱的時(shí)候前端請(qǐng)求會(huì)被直接命中MySQL 這層基本沒有壓力。如果你用的是 Django 默認(rèn)的 LocMemCache 緩存要注意它是進(jìn)程內(nèi)緩存多進(jìn)程部署時(shí)各進(jìn)程各存一份命中率會(huì)打折但開發(fā)和小規(guī)模使用完全夠用。生產(chǎn)環(huán)境可以考慮換成 Redis配置差異只在 settings 里增加一段 CACHES 配置代碼不用改。前端定時(shí)刷新的完整寫法是let timer null; function loadChart(params) { fetch(/api/daily_trend? new URLSearchParams(params)) .then(res res.json()) .then(res { if (res.code ! 0) return; chart.setOption({ xAxis: { data: res.data.dates }, series: [{ data: res.data.values }] }); }); } function startAutoRefresh(params) { if (timer) clearInterval(timer); timer setInterval(() loadChart(params), 30 * 60 * 1000); }注意setOption第二次調(diào)用時(shí)只需要傳變化的xAxis.data和series.dataECharts 會(huì)做 diff 合并不需要把完整配置重寫一遍。這個(gè)細(xì)節(jié)能讓圖表在刷新時(shí)保持縮放的視圖狀態(tài)用戶不會(huì)覺得頁面在閃。5. DjangoMySQL 可視化項(xiàng)目避坑手冊(cè)5 個(gè)高頻翻車點(diǎn)5.1 坑位一MySQL 驅(qū)動(dòng)裝不上Django 一直報(bào) Did you install mysqlclient?現(xiàn)象python manage.py migrate時(shí)報(bào)錯(cuò)說找不到 MySQL 驅(qū)動(dòng)或者pip install mysqlclient編譯報(bào)錯(cuò)提示缺少mysql_config。原因mysqlclient依賴本地 MySQL C 庫的 header 文件Windows 上最常見的問題是缺少 Visual C 編譯器Linux 上則需要libmysqlclient-dev系統(tǒng)包。解決直接換pymysql。在項(xiàng)目__init__.py里寫兩行代碼就能讓 Django 認(rèn)出 pymysqlimport pymysql pymysql.install_as_MySQLdb()這個(gè)操作是把 pymysql 偽裝成 MySQLdbDjango 的 MySQL 后端在 import 時(shí)會(huì)自動(dòng)調(diào)用它。相比下載預(yù)編譯的 mysqlclient wheel 包pymysql 是純 Python 實(shí)現(xiàn)安裝就是pip install pymysql一條命令沒有任何編譯依賴。5.2 坑位二中文顯示亂碼curl 接口返回 UTF-8 字符變成問號(hào)現(xiàn)象前端圖表里的站點(diǎn)名、城市名變成???或者寫進(jìn) MySQL 的中文讀出來是一串亂碼。原因數(shù)據(jù)庫建的字符集不是 utf8mb4。MySQL 5.7 及以下版本默認(rèn)字符集是 latin1Django 表結(jié)構(gòu)里的vachar字段跟著繼承了這個(gè)字符集中文字符被截?cái)啻娉闪藛柼?hào)。解決建庫語句顯式指定字符集寫入時(shí)在連接里也指定ALTER DATABASE air_quality_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ALTER TABLE station CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;ALTER TABLE ... CONVERT TO CHARACTER SET會(huì)重寫表里已有的數(shù)據(jù)如果數(shù)據(jù)已經(jīng)是亂碼重寫完還是亂碼需要重新導(dǎo)庫。所以最穩(wěn)妥的做法是在導(dǎo)入數(shù)據(jù)之前就把庫、表、連接三處字符集統(tǒng)一用第 2 章里的建庫語句不要等到看見亂碼再補(bǔ)救。5.3 坑位三數(shù)據(jù)庫表已經(jīng)有數(shù)據(jù)想加索引卻卡到超時(shí)現(xiàn)象往百萬行數(shù)據(jù)的表上加索引命令執(zhí)行半天沒完開發(fā)環(huán)境的 MySQL 直接報(bào) lock wait timeout。原因MySQL 5.6 之前的版本加索引會(huì)鎖表即使在 5.7 上用ALTER TABLE ADD INDEX也是在線 DDL但如果你用的 MySQL 版本較老或者有長事務(wù)在執(zhí)行加索引還是會(huì)阻塞讀寫。解決用pt-online-schema-change工具做無鎖變更或者分兩步處理先創(chuàng)建一張新表帶上索引再INSERT ... SELECT拷數(shù)據(jù)最后RENAME TABLE。對(duì)于數(shù)據(jù)量在幾十萬級(jí)別的場(chǎng)景最簡(jiǎn)單的辦法是確認(rèn)沒有別的連接在跑長事務(wù)后直接把lock_wait_timeout調(diào)大SET SESSION lock_wait_timeout 3600; ALTER TABLE air_quality_record ADD INDEX idx_pollutant_time (pollutant_id, record_time);如果索引加不上去影響到了整個(gè)接口的響應(yīng)時(shí)間這時(shí)候可行的路線是先把數(shù)據(jù)導(dǎo)入腳本跑完再一次性加上所有索引避免反復(fù) ALTER。5.4 坑位四Django 的 DateTimeField 寫入報(bào) ValueError: time data ... does not match format現(xiàn)象用datetime.strptime解析 CSV 里的一行時(shí)間字段報(bào)格式不匹配但肉眼看著數(shù)據(jù)格式明明一樣。原因CSV 里的時(shí)間精度可能不統(tǒng)一比如大部分是2025-01-01 00:00:00但偶爾有幾行是2025-01-01 0:00:00或2025/01/01 00:00:00strptime 的格式串只要對(duì)不上就拋異常。解決不要用死格式解析用dateutil.parser.parse做模糊解析from dateutil.parser import parse raw_time row[time] try: parsed_time parse(raw_time) except (ValueError, OverflowError): print(f無法解析的時(shí)間: {raw_time}) continuedateutil能識(shí)別多種常見格式省去你寫一堆try/except的邏輯。但要注意它解析2025/01/01時(shí)會(huì)按美式日期處理如果你有中文格式的2025年1月1日最好在導(dǎo)入前統(tǒng)一預(yù)處理成標(biāo)準(zhǔn)格式。5.5 坑位五接口偶發(fā) 500日志顯示 MySQL server has gone away現(xiàn)象圖表頁面剛打開時(shí)正常點(diǎn)了幾次切換條件之后突然報(bào)錯(cuò)重啟服務(wù)之后又恢復(fù)。原因MySQL 的wait_timeout默認(rèn)是 8 小時(shí)Django 這邊CONN_MAX_AGE設(shè)為 60 后連接在 8 小時(shí)內(nèi)空閑會(huì)被 MySQL 服務(wù)端主動(dòng)斷開Django 復(fù)用這條已失效的連接時(shí)就報(bào) gone away。這個(gè)坑在你開發(fā)調(diào)試時(shí)幾乎不會(huì)出現(xiàn)部署上線后流量低峰期最容易遇到。解決在 settings 里把CONN_MAX_AGE調(diào)小一些或者加一段連接校驗(yàn)的重試邏輯from django.db import close_old_connections # 在視圖入口處調(diào)用放棄已斷開的連接 close_old_connections()常見做法是每處理完一個(gè)請(qǐng)求就調(diào)用一次close_old_connectionsDjango 的 signal 機(jī)制會(huì)自動(dòng)做這件事但如果你用了多線程或異步任務(wù)就需要手動(dòng)加。另一個(gè)思路是改 MySQL 的wait_timeout為 28800 以上看能不能避開但治標(biāo)不治本還是建議在代碼層容忍失效連接。6. 部署后第一天就該做的驗(yàn)證數(shù)據(jù)一致性、告警線與壓測(cè)技巧6.1 一致性校驗(yàn)圖表數(shù)據(jù)對(duì)不上原始 CSV 的問題排查部署完成、頁面能出圖之后先別急著收工花十分鐘做一致性校驗(yàn)。抽查一個(gè)站點(diǎn)、一個(gè)時(shí)間范圍的聚合結(jié)果用 SQL 手算一遍對(duì)比前端展示的數(shù)值是否一致SELECT station_id, DATE(record_time) AS day, ROUND(AVG(value), 1) AS avg_pm25 FROM air_quality_record WHERE pollutant_id (SELECT id FROM pollutant WHERE codepm25) AND record_time BETWEEN 2025-01-01 AND 2025-01-07 GROUP BY station_id, DAY(record_time);把 SQL 結(jié)果和圖表上顯示的數(shù)字對(duì)一下如果差得多先從數(shù)據(jù)導(dǎo)入環(huán)節(jié)查。有幾個(gè)容易忽略的點(diǎn)CSV 里有的行是NA或者空值導(dǎo)入腳本里continue跳過之后日均值的分母會(huì)變導(dǎo)致濃度整體偏高或偏低同一時(shí)間同一站點(diǎn)有重復(fù)記錄導(dǎo)致聚合時(shí)被算了兩遍。用SELECT COUNT(*) FROM air_quality_record WHERE station_id1 AND record_time2025-01-01 00:00:00;可以快速驗(yàn)證有沒有重復(fù)有的話在導(dǎo)入腳本里加get_or_create或去重邏輯。我一般會(huì)在導(dǎo)入時(shí)額外輸出一份統(tǒng)計(jì)日志包括總行數(shù)、跳過行數(shù)、時(shí)間范圍起止、站點(diǎn)數(shù)量這樣將來數(shù)據(jù)對(duì)不上時(shí)能直接對(duì)照日志排查而不是等用戶發(fā)現(xiàn)圖表異常再回頭查。6.2 loadtest 壓測(cè)確認(rèn)你的可視化接口撐得住多看板同時(shí)在線部署完成后用django-extension的runserver_plus或者直接用abApache Bench壓一下接口底數(shù)。測(cè)試腳本只打最核心的聚合接口命令很簡(jiǎn)單ab -n 100 -c 10 http://127.0.0.1:8000/api/daily_trend?station_id1start2025-01-01end2025-01-31-n 100表示總共發(fā) 100 個(gè)請(qǐng)求-c 10表示同時(shí) 10 個(gè)并發(fā)?？磧蓚€(gè)值Time per request和Failed requests。如果平均響應(yīng)時(shí)間超過 2 秒先檢查視圖里有沒有count()做粗粒度判斷、有沒有緩存命中如果 Failed 不為 0往 MySQL 慢查詢?nèi)罩究匆谎塾袥]有全表掃描出現(xiàn)。壓測(cè)結(jié)束后把 Django 的DEBUG設(shè)為False再測(cè)一遍DEBUG 模式下 Django 會(huì)為每個(gè) SQL 查詢記錄執(zhí)行計(jì)劃開銷很大很多人上線后忘了關(guān)接口莫名變慢。6.3 一個(gè)小習(xí)慣把看板的數(shù)據(jù)刷新頻率和緩存過期時(shí)間寫進(jìn)配置我吃過大意虧之后養(yǎng)成了寫配置注釋的習(xí)慣。項(xiàng)目的settings.py里會(huì)有這樣一段# 數(shù)據(jù)更新頻率外部數(shù)據(jù)源每 30 分鐘更新一次 DATA_REFRESH_INTERVAL_SECONDS 30 * 60 # 緩存時(shí)間略大于數(shù)據(jù)更新間隔避免邊緣請(qǐng)求打穿緩存 CACHE_TIMEOUT DATA_REFRESH_INTERVAL_SECONDS 60所有和數(shù)據(jù)新鮮度相關(guān)的值集中在一個(gè)文件中定版后不分散在各個(gè)視圖里。這樣做的好處是將來數(shù)據(jù)源的更新頻率變了只改一個(gè)常量前端定時(shí)刷新的間隔也可以動(dòng)態(tài)暴露成接口字段不用每次改完再發(fā)一次前端代碼?？梢暬?xiàng)目看著不難上線后真正消耗精力的永遠(yuǎn)是數(shù)據(jù)對(duì)不上和慢查詢把這兩個(gè)問題在部署頭一天解決掉后面就是省心的看板了。這個(gè)方向項(xiàng)目還有一個(gè)容易被忽略的優(yōu)勢(shì)它天然適合你在求職時(shí)講性能優(yōu)化的故事——從慢查詢到加索引、從逐條插入到批量寫入、從無緩存到帶超時(shí)的緩存層每一個(gè)點(diǎn)都是能展開講十分鐘的真實(shí)經(jīng)歷。希望你在自己動(dòng)手跑通數(shù)據(jù)鏈路的過程中也能收獲同樣的底氣和判斷力。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取