簡(jiǎn)介這是一份基于Django與MySQL實(shí)現(xiàn)的城市PM2.5空氣質(zhì)量數(shù)據(jù)可視化分析源碼面向需要完成Python課程設(shè)計(jì)、畢業(yè)設(shè)計(jì)或希望快速上手Web可視化開(kāi)發(fā)的讀者。項(xiàng)目包含完整的Django工程結(jié)構(gòu)內(nèi)置北京、上海、廣州、成都、沈陽(yáng)等城市六年P(guān)M2.5數(shù)據(jù)覆蓋溫度、濕度、露點(diǎn)、風(fēng)向、大氣壓等影響因子并提供登錄注冊(cè)、數(shù)據(jù)篩選、圖表展示等功能。壓縮包共66個(gè)文件以17個(gè)py源碼文件、24個(gè)csv數(shù)據(jù)文件、4個(gè)xml配置、3個(gè)html頁(yè)面和2個(gè)md文檔為主同時(shí)包含SQL數(shù)據(jù)庫(kù)腳本、依賴清單與詳細(xì)部署文檔整體大小僅12.38MB目錄清晰便于按模塊學(xué)習(xí)。目前已有145人學(xué)習(xí)下載。借助這份資源讀者可以直接替換CSV數(shù)據(jù)完成自己的可視化分析也可從數(shù)據(jù)預(yù)處理腳本、Django視圖配置和前端模板中理解完整的項(xiàng)目組織方式是兼具實(shí)用性與教學(xué)價(jià)值的Python高分參考項(xiàng)目。1. 拿到這份 PM2.5 可視化源碼先認(rèn)清它到底解決什么問(wèn)題當(dāng)一張城市空氣質(zhì)量數(shù)據(jù)表落到你手里你能看到的只是幾百行數(shù)字哪個(gè)站點(diǎn)、哪個(gè)時(shí)刻、PM2.5 濃度多少?？蓳Q到業(yè)務(wù)或答辯現(xiàn)場(chǎng)對(duì)方要的是在瀏覽器里按城市、按時(shí)間段拖出趨勢(shì)線和柱狀圖甚至能一眼看出哪幾天污染爆表?；?Django MySQL 實(shí)現(xiàn)的城市 PM2.5 空氣質(zhì)量數(shù)據(jù)可視化分析源碼做的就是這件事用 Django 把數(shù)據(jù)庫(kù)里的時(shí)序數(shù)據(jù)整理成網(wǎng)頁(yè)接口再用 ECharts 這類前端圖表把 PM2.5、PM10、AQI 變成可交互圖形。它適合兩類人一類是需要課程設(shè)計(jì)或求職作品的 Python 學(xué)習(xí)者想找一個(gè)“后端 數(shù)據(jù)庫(kù) 可視化”都占全的完整項(xiàng)目另一類是環(huán)保、氣象相關(guān)崗位上想把監(jiān)測(cè)數(shù)據(jù)快速做成內(nèi)部看板的后臺(tái)開(kāi)發(fā)。下面我把這套項(xiàng)目的表結(jié)構(gòu)、導(dǎo)數(shù)流程、接口設(shè)計(jì)和部署排錯(cuò)完整拆開(kāi)照著搭就能跑通。2. Django MySQL 的數(shù)據(jù)模型與項(xiàng)目骨架先把表設(shè)計(jì)對(duì)再談可視化2.1 為什么是這個(gè)組合Django 管業(yè)務(wù)MySQL 扛數(shù)據(jù)PM2.5 可視化這類項(xiàng)目選型時(shí)最常見(jiàn)的兩個(gè)替代方案是 Flask SQLite 和 Django SQLite。從小項(xiàng)目角度看 Flask 更輕但如果最終要讓數(shù)據(jù)可視化長(zhǎng)期可維護(hù)Django MySQL 的優(yōu)勢(shì)在幾個(gè)地方Django 自帶 Admin 后臺(tái)、ORM、數(shù)據(jù)遷移腳本、表單校驗(yàn)做一個(gè)“后臺(tái)錄入 前端展示”的全棧項(xiàng)目時(shí)不用東拼西補(bǔ)MySQL 對(duì)多用戶并發(fā)寫入的支持比 SQLite 好尤其當(dāng)你有定時(shí)任務(wù)每小時(shí)拉一批監(jiān)測(cè)數(shù)據(jù)進(jìn)來(lái)另一側(cè)瀏覽器同時(shí)在查圖表SQLite 很容易報(bào)出 database is locked。MySQL 有行級(jí)鎖和連接池寫入和查詢可以并行不打架。當(dāng)然選 MySQL 不是沒(méi)有代價(jià)你得先裝好數(shù)據(jù)庫(kù)、建庫(kù)建用戶、把驅(qū)動(dòng)包裝對(duì)。這也是為什么很多新手卡在第 0 步就放棄了——Django 代碼還沒(méi)寫MySQL 先給了一記下馬威。我的建議是環(huán)境問(wèn)題集中花半天解決后面收益是值得的課程設(shè)計(jì)、論文實(shí)驗(yàn)和企業(yè)內(nèi)部看板這套組合都能直接用。2.2 數(shù)據(jù)表怎么拆站點(diǎn)維表、城市維表、空氣質(zhì)量事實(shí)表空氣質(zhì)量數(shù)據(jù)可視化最常見(jiàn)的臟做法是把所有字段塞進(jìn)一張表城市名、站點(diǎn)名、時(shí)間、PM2.5、再帶上 SO2、NO2、O3……表也能跑但等你要做“對(duì)比北京和上海 2024 年上半年日均 PM2.5”的查詢時(shí)SQL 會(huì)寫得非常別扭而且城市名重復(fù)存儲(chǔ)會(huì)帶來(lái)大量冗余。更合理的做法是拆成維度表和事實(shí)表城市是一張表監(jiān)測(cè)站點(diǎn)是一張表逐小時(shí)監(jiān)測(cè)記錄單獨(dú)放一張大表用外鍵關(guān)聯(lián)。一張能支撐可視化的最小模型長(zhǎng)這樣# monitor/models.py from django.db import models class City(models.Model): name models.CharField(max_length32, uniqueTrue) class Meta: db_table dim_city ordering [name] def __str__(self): return self.name class Station(models.Model): code models.CharField(max_length16, uniqueTrue) # 站點(diǎn)編碼例如 CD_1001A name models.CharField(max_length64) city models.ForeignKey(City, on_deletemodels.CASCADE, related_namestations) class Meta: db_table dim_station def __str__(self): return self.name class AirQuality(models.Model): station models.ForeignKey(Station, on_deletemodels.CASCADE, related_namerecords) monitor_time models.DateTimeField(db_indexTrue) # 監(jiān)測(cè)時(shí)間查詢熱字段 pm25 models.DecimalField(max_digits6, decimal_places2, nullTrue) pm10 models.DecimalField(max_digits6, decimal_places2, nullTrue) aqi models.IntegerField(nullTrue) class Meta: db_table fact_air_quality unique_together (station, monitor_time) # 同一站點(diǎn)同一時(shí)刻只留一條這里最關(guān)鍵的兩個(gè)設(shè)計(jì)是db_indexTrue和unique_together。monitor_time建索引是因?yàn)榭梢暬涌诨径紩?huì)按時(shí)間范圍過(guò)濾不建索引的話百萬(wàn)行記錄會(huì)全表掃unique_together則從數(shù)據(jù)庫(kù)層擋住了重復(fù)數(shù)據(jù)比在導(dǎo)入腳本里手動(dòng)判重可靠得多。2.3 創(chuàng)建 Django app 與連接 MySQL 的配置順序模型設(shè)計(jì)好之后先把這個(gè)數(shù)據(jù)入庫(kù)的流程走通再做接口。常見(jiàn)做法是手動(dòng)創(chuàng)建名為 monitor 的應(yīng)用然后配置數(shù)據(jù)庫(kù)連接并執(zhí)行遷移。按這個(gè)順序走python manage.py startapp monitor python manage.py makemigrations monitor python manage.py migratestartapp會(huì)自動(dòng)生成 migration、views、models 這些文件makemigrations monitor把模型翻譯成遷移腳本第一次執(zhí)行時(shí)如果提示 No changes detected多半是 settings 的 INSTALLED_APPS 里沒(méi)有加monitor這是新手第一個(gè)高頻翻車點(diǎn)。連接 MySQL 時(shí)settings.py 里這段配置可以直接抄# config/settings.py 片段 import os DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: os.getenv(DB_NAME, air_quality), USER: os.getenv(DB_USER, root), PASSWORD: os.getenv(DB_PASSWORD, change_me), HOST: os.getenv(DB_HOST, 127.0.0.1), PORT: os.getenv(DB_PORT, 3306), OPTIONS: { charset: utf8mb4, init_command: SET sql_modeSTRICT_TRANS_TABLES, }, } }charset: utf8mb4建議保留它決定中文備注和城市名能不能正常存取init_command里的 sql_mode 會(huì)避免 MySQL 對(duì)非法日期做靜默轉(zhuǎn)換寧可導(dǎo)入報(bào)錯(cuò)也不能讓臟日期悄悄進(jìn)庫(kù)。密碼不要直接寫死在代碼里用環(huán)境變量或者本地.env都好這個(gè)項(xiàng)目將來(lái)要示人或者部署配置文件會(huì)被其他人看到。數(shù)據(jù)庫(kù)本身需要在 MySQL 里先建好Django 的 migrate 只會(huì)建表不會(huì)幫你建庫(kù)。我一般用這么一句CREATE DATABASE air_quality DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;建庫(kù)這一步有講究如果直接用默認(rèn) latin1 建庫(kù)后面所有中文都是問(wèn)號(hào)還得推倒重來(lái)。遷移完成后可以用python manage.py shell手工插入一條測(cè)試數(shù)據(jù)再用 SELECT 驗(yàn)證一遍中文存取這一步值得做避免后面接口都寫完了才發(fā)現(xiàn)數(shù)據(jù)庫(kù)字符集不對(duì)。3. 把 PM2.5 采樣數(shù)據(jù)清洗入庫(kù)管理命令腳本與去重策略3.1 原始數(shù)據(jù)長(zhǎng)什么樣CSV 的編碼和無(wú)效值最坑從公開(kāi)監(jiān)測(cè)站點(diǎn)拿到的 PM2.5 原始數(shù)據(jù)最常見(jiàn)的是 CSV 或 Excel 導(dǎo)出的表格。列一般包括站點(diǎn)編號(hào)、時(shí)間、PM2.5、PM10、SO2、NO2、O3、CO 這些。這里最容易翻車的不是數(shù)據(jù)量而是三件事文件編碼可能是 UTF-8 帶 BOM也可能是 GBK缺測(cè)值有空白、有-999、還有--這樣亂寫的時(shí)間列格式不統(tǒng)一有的是2025-01-01 08:00有的是2025/1/1 8:00。在寫任何導(dǎo)入腳本之前我建議先花兩分鐘看一眼文件頭部file data/pm25_2025.csv head -n 5 data/pm25_2025.csvfile命令輸出里有UTF-8 (with BOM)或ISO-8859字樣直接決定你用utf-8-sig還是gbk去讀。打開(kāi)看到\ufeff開(kāi)頭的表頭就說(shuō)明有 BOMPython 里用encodingutf-8-sig可以自動(dòng)吃掉它。3.2 寫一個(gè) Django 管理命令做批量導(dǎo)入bulk_create 是唯一正解手動(dòng)在 shell 里一條條創(chuàng)建對(duì)象只適合調(diào)試。正式導(dǎo)數(shù)據(jù)要寫成 Django management command好處是能復(fù)用項(xiàng)目的 settings 和 ORM將來(lái)部署到服務(wù)器上可以直接用python manage.py import_pm25 --csv ...觸發(fā)。一個(gè)最小可用的導(dǎo)入命令如下# monitor/management/commands/import_pm25.py import csv from datetime import datetime from django.core.management.base import BaseCommand, CommandError from django.utils import timezone from monitor.models import City, Station, AirQuality def parse_float(value): 把 CSV 里的無(wú)效值統(tǒng)一轉(zhuǎn)成 None而不是強(qiáng)行填充 0。 if value is None: return None value str(value).strip() if value in (, -, --, null, 999, -999): return None try: return float(value) except ValueError: return None class Command(BaseCommand): help 導(dǎo)入 PM2.5 站點(diǎn)監(jiān)測(cè) CSV 數(shù)據(jù) def add_arguments(self, parser): parser.add_argument(--csv, requiredTrue, helpCSV 文件路徑) parser.add_argument(--city, requiredTrue, help城市名例如 北京) parser.add_argument(--station, requiredTrue, help站點(diǎn)編碼) def handle(self, *args, **options): city, _ City.objects.get_or_create(nameoptions[city]) station, _ Station.objects.get_or_create( codeoptions[station], defaults{name: options[station], city: city} ) rows [] skipped 0 with open(options[csv], encodingutf-8-sig) as fp: reader csv.DictReader(fp) for line in reader: try: t datetime.strptime(line[time], %Y-%m-%d %H:%M) except (ValueError, KeyError): skipped 1 continue rows.append(AirQuality( stationstation, monitor_timet, pm25parse_float(line.get(pm25)), pm10parse_float(line.get(pm10)), aqiint(parse_float(line.get(aqi)) or 0) or None, )) # ignore_conflictsTrue 依賴數(shù)據(jù)庫(kù)層的唯一約束命中就跳過(guò) AirQuality.objects.bulk_create(rows, batch_size2000, ignore_conflictsTrue) self.stdout.write(self.style.SUCCESS(f導(dǎo)入完成{len(rows)} 條跳過(guò) {skipped} 條新增去重后數(shù)據(jù)))這段腳本里兩個(gè)參數(shù)必須解釋清楚。batch_size2000控制每次 INSERT 的記錄數(shù)太大容易超過(guò) MySQL 的 max_allowed_packet太小又體現(xiàn)不出批量插入的優(yōu)勢(shì)我長(zhǎng)期用 2000 這個(gè)值沒(méi)出過(guò)問(wèn)題。ignore_conflictsTrue是配合模型里的unique_together使用的意思是遇到同一個(gè)站點(diǎn)同一時(shí)刻的重復(fù)記錄直接跳過(guò)不報(bào)錯(cuò)、不覆蓋這比先 SELECT 再 INSERT 的方式快一個(gè)數(shù)量級(jí)也不用自己維護(hù)去重邏輯。parse_float的取舍也要注意我把空值和-999這類典型缺測(cè)標(biāo)記統(tǒng)一轉(zhuǎn)成None而不是填 0。數(shù)據(jù)可視化時(shí) 0 會(huì)被畫成一條貼地的線很容易被誤讀為“空氣質(zhì)量很好”而 None 可以讓前端顯示為空缺圖表更誠(chéng)實(shí)。AQI 那行寫得稍微繞了一點(diǎn)是為了兼容 CSV 里沒(méi)有 aqi 列的情況。3.3 數(shù)據(jù)質(zhì)量邊界臟數(shù)據(jù)處理到什么程度該收手很多人拿到數(shù)據(jù)第一反應(yīng)是用 pandas 把缺測(cè)值 fillna(0)把異常值刪掉再入庫(kù)。這個(gè)思路對(duì) pandas 分析沒(méi)問(wèn)題但對(duì)可視化項(xiàng)目未必合適。監(jiān)測(cè)站的-999和空值只是“沒(méi)測(cè)到”不代表濃度為零擅自把異常值刪掉又會(huì)造成時(shí)間序列斷檔。我一般只在三個(gè)地方做處理格式非法的時(shí)間行直接跳過(guò)PM2.5 為負(fù)但不在-999這種約定范圍內(nèi)的值轉(zhuǎn) None重復(fù)記錄交給數(shù)據(jù)庫(kù)唯一約束去擋。其余數(shù)值保持原樣入庫(kù)重度清洗留給后續(xù)分析腳本不要把清洗邏輯在導(dǎo)入環(huán)節(jié)做死。另外有個(gè)經(jīng)驗(yàn)一個(gè)城市可能對(duì)應(yīng)多個(gè)站點(diǎn)導(dǎo)入時(shí)--station參數(shù)必須真實(shí)存在否則air_quality表里所有記錄都會(huì)掛在同一個(gè)站點(diǎn)下后面按站點(diǎn)維度的圖表全都會(huì)失真。如果你的 CSV 里本身帶了站點(diǎn)編號(hào)列那就應(yīng)該從 CSV 中讀取站點(diǎn)而不是用命令行參數(shù)硬指定我最早就是偷懶用命令行參數(shù)結(jié)果導(dǎo)了十幾個(gè)站點(diǎn)的數(shù)據(jù)全部串成了同一個(gè)站點(diǎn)。4. 可視化層怎么搭REST 接口 ECharts 圖表聯(lián)動(dòng)4.1 只讀接口不需要 DRFDjango 原生 View 就夠用代碼里如果數(shù)據(jù)表和導(dǎo)入都搞定了接下來(lái)就是把這個(gè)項(xiàng)目最好看的可視化部分搭起來(lái)。很多人在這一步會(huì)直接引入 Django REST Framework寫 serializer、寫 router。但如果你只是要從數(shù)據(jù)庫(kù)讀出聚合結(jié)果、返回 JSON 給前端原生 Django View 完全夠用少一層依賴部署時(shí)也少一點(diǎn)版本兼容問(wèn)題。等以后真要加登錄鑒權(quán)、分頁(yè)、過(guò)濾、API 文檔再遷移到 DRF 也不遲。以“城市 PM2.5 趨勢(shì)”接口為例最核心的視圖可以這樣寫# monitor/views.py from django.http import JsonResponse from django.utils.dateparse import parse_datetime from django.views import View from django.db.models import Avg from django.db.models.functions import TruncHour, TruncDay from monitor.models import AirQuality class CityTrendView(View): 按城市和時(shí)間范圍返回 PM2.5 聚合值支持按小時(shí)或按天聚合。 def get(self, request, city_id): start parse_datetime(request.GET.get(start, )) end parse_datetime(request.GET.get(end, )) if start is None or end is None or start end: return JsonResponse({error: start 和 end 參數(shù)必填且 start 需早于 end}, status400) granularity request.GET.get(granularity, day) trunc_expr TruncHour(monitor_time) if granularity hour else TruncDay(monitor_time) rows ( AirQuality.objects .filter(station__city_idcity_id, monitor_time__range(start, end)) .annotate(buckettrunc_expr) .values(bucket) .annotate(avg_pm25Avg(pm25)) .order_by(bucket) ) payload [ { t: item[bucket].strftime(%Y-%m-%d %H:%M), pm25: round(item[avg_pm25], 2) if item[avg_pm25] is not None else None, } for item in rows ] return JsonResponse(payload, safeFalse)這個(gè)視圖有幾個(gè)細(xì)節(jié)值得展開(kāi)。TruncHour和TruncDay是 Django 提供的數(shù)據(jù)庫(kù)時(shí)間截?cái)嗪瘮?shù)它會(huì)在 SQL 層完成DATE_FORMAT這類操作比把所有明細(xì)拉回 Python 再按時(shí)間分組快得多也避免了時(shí)區(qū)被 Python 側(cè)二次解釋。values(bucket)配合annotate(Avg(pm25))是標(biāo)準(zhǔn)的 group by 寫法注意聚合結(jié)果字段名是avg_pm25前端拿到的 JSON 里就是這個(gè)鍵不要寫成pm25__avg這種自動(dòng)名那樣前端代碼會(huì)很難看。avg_pm25可能是 None響應(yīng)里保留顯式 null讓前端圖表能跳過(guò)空缺點(diǎn)。URL 配置同樣很直接不需要注冊(cè)到 DRF router# config/urls.py from django.urls import path from monitor.views import CityTrendView urlpatterns [ path(api/city/int:city_id/trend/, CityTrendView.as_view(), namecity-trend), ]int:city_id會(huì)做參數(shù)類型轉(zhuǎn)換傳入視圖的是一個(gè) Python int不是字符串。接口寫好后先用 Django 測(cè)試客戶端試一下python manage.py shell里用Client().get(/api/city/1/trend/, {start: ..., end: ...})這一步確認(rèn)能返回 JSON再寫前端避免前后端同時(shí)出錯(cuò)時(shí)不知道鍋該甩給誰(shuí)。4.2 ECharts 接數(shù)據(jù)折線圖先跑通再擴(kuò)展熱力圖前端可視化我默認(rèn)用 ECharts因?yàn)閲?guó)內(nèi)能檢索到的數(shù)據(jù)可視化示例幾乎一半以上都是用 ECharts 做的折線圖、柱狀圖、地圖熱力圖都有成熟配置。頁(yè)面里通常先準(zhǔn)備一個(gè)容器 div再在腳本里初始化圖表// templates/index.html 中內(nèi)聯(lián)或單獨(dú) static/js/trend.js const chart echarts.init(document.getElementById(trendChart)); function loadTrend(cityId, start, end) { fetch(/api/city/${cityId}/trend/?start${encodeURIComponent(start)}end${encodeURIComponent(end)}granularityday) .then(res res.json()) .then(data { chart.setOption({ tooltip: { trigger: axis }, xAxis: { type: category, data: data.map(d d.t) }, yAxis: { type: value, name: μg/m3 }, series: [{ name: PM2.5, type: line, connectNulls: false, data: data.map(d d.pm25) }] }); }); }connectNulls: false在這里很關(guān)鍵。接口返回的pm25字段如果是 null折線要斷開(kāi)而不是用直線跨越缺口否則會(huì)讓人誤以為那段時(shí)間濃度是連續(xù)變化的。如果數(shù)據(jù)跨度是一整年、粒度選了 hour折線會(huì)上萬(wàn)個(gè)點(diǎn)瀏覽器渲染會(huì)卡頓此時(shí)要么把粒度切到 day要么在接口里再做一次 LIMIT。接口里沒(méi)有寫死 LIMIT是因?yàn)檫@類內(nèi)部看板的需求變化很快我個(gè)人更傾向于在 URL 參數(shù)里暴露 granularity把前端的展示壓力交給用戶選擇。4.3 頁(yè)面模板與靜態(tài)資源別把接口地址寫死在 localhost模板頁(yè)面放在 Django 的 templates 目錄圖表 JS 和 ECharts 庫(kù)放在 static 目錄。有一個(gè)特別常見(jiàn)的坑是本地開(kāi)發(fā)時(shí)接口地址寫http://127.0.0.1:8000/api/...一切正常部署到服務(wù)器后就空白因?yàn)闉g覽器地址變了但 JS 里的 localhost 沒(méi)變。我一般會(huì)在模板里把接口前綴注入到全局變量!-- templates/index.html -- script window.API_BASE {% url city-trend city_id1 %}.replace(/api/city/1/trend/, /api); /script這樣前端只要基于API_BASE拼路徑本地和服務(wù)器都能用相對(duì)地址省去部署時(shí)改代碼的麻煩。ECharts 本身是純前端庫(kù)建議把它下載到static/vendor/echarts.min.js不要用 CDN。城市級(jí)可視化項(xiàng)目經(jīng)常部署在不能訪問(wèn)外網(wǎng)的內(nèi)網(wǎng)環(huán)境CDN 一斷圖表就全白這是很多新手連 ECharts 的邊都摸不到就開(kāi)始懷疑后端接口的原因。5. 部署與開(kāi)發(fā)排錯(cuò)PM2.5 可視化項(xiàng)目最常見(jiàn)的 5 個(gè)坑5.1 MySQL 8.0 連不上Authentication plugin 報(bào)錯(cuò)現(xiàn)象python manage.py migrate時(shí)報(bào)django.db.utils.OperationalError: Authentication plugin caching_sha2_password cannot be loaded。原因MySQL 8.0 默認(rèn)認(rèn)證插件是 caching_sha2_password而 PyMySQL 版本過(guò)舊或系統(tǒng)里的 mysqlclient 不認(rèn)這個(gè)插件。解決升級(jí)依賴庫(kù)在 requirements.txt 里把 PyMySQL 版本寫新一點(diǎn)并在項(xiàng)目的__init__.py里顯式注冊(cè)# config/__init__.py import pymysql pymysql.install_as_MySQLdb()如果你用的是 mysqlclient則優(yōu)先檢查系統(tǒng)是否裝了 libmysqlclient-dev 這類底層庫(kù)。也可以在 MySQL 里為項(xiàng)目單獨(dú)創(chuàng)建用戶指定使用 mysql_native_password 插件但這屬于臨時(shí)方案新庫(kù)還是建議升級(jí)驅(qū)動(dòng)畢竟 MySQL 8.4 之后 mysql_native_password 也開(kāi)始被邊緣化。5.2 中文亂碼寫入是問(wèn)號(hào)讀出來(lái)也是問(wèn)號(hào)現(xiàn)象城市名“北京”在 Django Admin 里顯示為??—?o?或??。原因建庫(kù)時(shí)用了默認(rèn)字符集或者表不是 utf8mb4或者 Django 連接串沒(méi)指定 charset。解決從三個(gè)層面拉齊——建庫(kù)時(shí)顯式指定DEFAULT CHARACTER SET utf8mb4settings 的OPTIONS里寫charset: utf8mb4打開(kāi) MySQL 客戶端連接時(shí)執(zhí)行SET NAMES utf8mb4。數(shù)據(jù)已經(jīng)亂掉的場(chǎng)景沒(méi)有后悔藥只能清空重導(dǎo)所以建庫(kù)時(shí)這道命令一定不要省。5.3 時(shí)間錯(cuò)位早上 8 點(diǎn)的數(shù)據(jù)跑到了 0 點(diǎn)現(xiàn)象接口返回的 JSON 里時(shí)間比原始 CSV 少了 8 小時(shí)或者圖表橫軸每天從 16 點(diǎn)開(kāi)始。原因Django 默認(rèn)TIME_ZONE UTC而 CSV 里的時(shí)間是北京時(shí)間Django 的 DateTimeField 一旦啟用USE_TZ True存庫(kù)時(shí)會(huì)按 UTC 轉(zhuǎn)換。解決settings 里改時(shí)區(qū)配好后重新導(dǎo)數(shù)據(jù)LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai USE_TZ True注意這里USE_TZ True保留讓 ORM 自動(dòng)處理時(shí)區(qū)轉(zhuǎn)換配合前端只顯示monitor_time的本地時(shí)間字符串即可。另一個(gè)相關(guān)問(wèn)題是聚合查詢里的TruncHour在 MySQL 中會(huì)基于數(shù)據(jù)庫(kù)會(huì)話時(shí)區(qū)計(jì)算最好在連接數(shù)據(jù)庫(kù)前確認(rèn)連接時(shí)區(qū)。血淚經(jīng)驗(yàn)是先寫一個(gè)腳本隨機(jī)抽幾條記錄比對(duì) CSV 原時(shí)間和接口返回時(shí)間再做可視化別等圖表出來(lái)了才發(fā)現(xiàn)整體平移了 8 小時(shí)。5.4 接口慢一次查一年數(shù)據(jù)卡了 5 秒現(xiàn)象折線圖加載時(shí)接口耗時(shí) 4000ms請(qǐng)求體 200KB前端渲染也卡。原因粒度使用了小時(shí)但查詢跨度是一年返回上萬(wàn)個(gè)聚合點(diǎn)或者模型沒(méi)寫db_index時(shí)間范圍過(guò)濾是全表掃描。解決先把接口默認(rèn)粒度改成 day再用EXPLAIN或 Django 的connection.queries看有沒(méi)有走索引最后在AirQuality表上加復(fù)合索引讓過(guò)濾和排序同時(shí)受益class Meta: db_table fact_air_quality unique_together (station, monitor_time) indexes [ models.Index(fields[monitor_time, station], nameidx_time_station), ]做了這一步同一份數(shù)據(jù)接口耗時(shí)基本能降到原來(lái)的十分之一?？梢暬?xiàng)目一旦數(shù)據(jù)進(jìn)入十萬(wàn)行索引和聚合粒度就是兩個(gè)最關(guān)鍵的調(diào)優(yōu)點(diǎn)。5.5 圖表白屏HTML 加載了但 ECharts 不渲染現(xiàn)象打開(kāi)頁(yè)面看到按鈕和標(biāo)題圖表區(qū)域空白瀏覽器 F12 里報(bào)echarts is not defined或 404。原因引用的是 CDN 上的 echart.min.js內(nèi)網(wǎng)環(huán)境加載失敗或者 Django 的DEBUG False時(shí)靜態(tài)文件路由失效。解決先把 ECharts 庫(kù)下載到本地 static然后確認(rèn) settings 配置STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static]開(kāi)發(fā)階段保持DEBUG True部署到 Nginx 時(shí)把/static/一起代理給 Nginx 處理不要讓 Django 承擔(dān)靜態(tài)文件服務(wù)。如果 Nginx 配好后仍然白屏先 curl 一下http://你的域名/static/vendor/echarts.min.js確認(rèn)這個(gè)文件在服務(wù)器上真實(shí)存在而不是部署時(shí) static 目錄沒(méi)同步過(guò)去。6. 驗(yàn)證接口與進(jìn)階方向從“能跑”到“能上線”6.1 用 Django TestCase 給接口上保險(xiǎn)這個(gè)項(xiàng)目最脆弱的部分不是前端而是接口的查詢參數(shù)。只要有人把start傳錯(cuò)格式或者數(shù)據(jù)庫(kù)里混進(jìn)了空值接口就會(huì)花式報(bào)錯(cuò)。我會(huì)用 Django 自帶的 TestCase 寫最小回歸驗(yàn)證確保改表結(jié)構(gòu)或加索引時(shí)不破壞接口# monitor/tests.py from django.test import TestCase from django.test import Client from django.utils import timezone from monitor.models import City, Station, AirQuality class CityTrendApiTest(TestCase): def setUp(self): self.city City.objects.create(name測(cè)試城市) self.station Station.objects.create(codeTEST_01, name測(cè)試站, cityself.city) AirQuality.objects.create( stationself.station, monitor_timetimezone.now(), pm2512.5, pm1035.0, ) def test_trend_returns_json_with_daily_avg(self): resp Client().get(/api/city/{}/trend/.format(self.city.id), { start: 2025-01-01T00:00, end: 2025-12-31T23:59, granularity: day, }) self.assertEqual(resp.status_code, 200) self.assertIn(pm25, resp.json()[0])這個(gè)測(cè)試斷言了接口返回 200 且包含pm25字段后面你改接口參數(shù)名、改聚合字段名時(shí)測(cè)試能直接提醒你前端同事也會(huì)跟著遭殃。跑一遍python manage.py test monitor幾秒鐘就能證明這個(gè)可視化項(xiàng)目的后端是可靠的。6.2 從看板到監(jiān)測(cè)產(chǎn)品AQI 分級(jí)、定時(shí)采集、預(yù)警推送基礎(chǔ)可視化跑通之后值得投入的三個(gè)方向是加 AQI 計(jì)算邏輯和污染等級(jí)配色而不是只展示一個(gè) PM2.5 數(shù)值用系統(tǒng) crontab 或 Celery beat 每小時(shí)拉一次監(jiān)測(cè)站數(shù)據(jù)保持看板實(shí)時(shí)在 PM2.5 連續(xù)三小時(shí)超過(guò)閾值時(shí)給業(yè)務(wù)群推送告警。這三個(gè)方向都能在你的課程設(shè)計(jì)說(shuō)明或項(xiàng)目文檔里作為亮點(diǎn)出現(xiàn)也和我做項(xiàng)目的習(xí)慣一致——可視化不是終點(diǎn)是數(shù)據(jù)被人使用和響應(yīng)的起點(diǎn)。做第一個(gè)版本時(shí)我曾在時(shí)區(qū)配置上翻了車整張圖表和真實(shí)監(jiān)測(cè)數(shù)據(jù)差了 8 小時(shí)后來(lái)每次接到時(shí)序數(shù)據(jù)項(xiàng)目第一件事就是先把“源數(shù)據(jù)時(shí)間 → 數(shù)據(jù)庫(kù)存儲(chǔ)時(shí)間 → 接口返回時(shí)間”全鏈路比對(duì)一遍。這個(gè)習(xí)慣幫我避掉了后續(xù)大量返工。如果你照著這套步驟把 PM2.5 可視化項(xiàng)目跑通后面換城市、換污染因子、換數(shù)據(jù)庫(kù)都只是參數(shù)級(jí)改動(dòng)希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取