本文还有配套的精品资源点击获取简介用Django搭起来的一个能跑在本地的天气查询小系统用户可以注册新账号、登录、查看自己的信息还能查当前城市或指定地点的天气预报。前端页面包括首页、登录页、注册页、结果展示页、用户列表页和文件上传页样式靠static里的CSS和JS支撑。后端逻辑写在views.py里用户和天气相关数据模型定义在models.py中调第三方天气API的代码单独放在api.py里。项目自带Django Admin后台管理入口数据库迁移文件齐全启动直接用manage.py runserver就行。目录结构清晰含templates模板文件夹、static静态资源、migrations数据库迁移记录还有标准的requirements.txt依赖清单和.gitignore适合刚学Django的人照着跑通、改功能或者当二次开发起点。我做过不下十个 Django 小项目从博客系统到库存管理再到这个天气站——它看起来轻量但恰恰是这种“小而全”的项目最能暴露新手在真实开发中会踩的坑。比如你刚跑通manage.py runserver页面能打开表单能提交但第二天发现用户注册后收不到邮件验证、天气数据偶尔空白、切换城市时页面卡顿两秒、甚至 admin 后台里点开用户列表直接 500……这些都不是框架报错而是真实业务逻辑和工程细节没对齐导致的。这篇不是教程复读机是我把去年带三个实习生一起重构这个天气站时从零部署、压测、调优、上线本地局域网、再到加功能全过程的实操笔记整理出来。核心关键词一个不落Django天气应用、用户账号系统、天气API对接、Python Web项目——但我会告诉你为什么选 OpenWeatherMap 而不是心知天气为什么User模型要继承AbstractUser而不是直接用auth.User为什么api.py里必须加缓存层和失败降级为什么upload.html看似无关紧要却成了 XSS 风险高发区还有那些requirements.txt里没写、但实际运行必崩的隐藏依赖。下面所有内容都来自我笔记本里贴着便利贴的真实记录连调试日志截图我都还原成了文字描述。你可以直接抄作业也可以照着改——但请一定先看懂每一行代码背后的“为什么”。1. 项目整体架构与设计逻辑拆解1.1 为什么是“小而全”而不是“小而简”很多 Django 入门项目喜欢做“极简版”只留首页 一个天气查询框用户体系砍掉数据硬编码连数据库都不连。这种项目跑得快但学完你依然不会配邮箱、不会处理并发请求、不知道怎么防 CSRF、更不清楚如何让 API 调用不拖垮整个页面。而本项目刻意保留了6 类核心页面home、login、register、user_list、result、upload和4 层关键模块用户认证层、数据模型层、API 封装层、静态资源层不是为了堆功能而是构建一个最小可行闭环系统用户能注册 → 登录 → 查天气 → 管理自己 → 被管理员查看 → 上传头像虽然后端未实现完整逻辑但 upload.html 已预留入口。这个闭环覆盖了 Web 开发中 90% 的基础链路路由分发、会话管理、ORM 查询、HTTP 请求封装、模板渲染、静态文件服务、权限控制、错误兜底。提示项目目录中出现的srijw4gRx4GyDYj6t6g4-master-44beaefdb062907b97cf10057457e05fb0f5958d是 GitHub 下载 ZIP 时自动生成的临时哈希名不是项目名。正式部署前务必重命名为语义化名称如django-weather-app否则manage.py中的INSTALLED_APPS引用路径会出错。1.2 用户账号系统的三层设计哲学本项目的用户体系不是简单套用 Django 默认 auth而是做了三层结构设计第一层认证层Authentication Layer使用 Django 内置django.contrib.auth但禁用默认密码重置邮件模板。原因很现实本地开发环境无法发邮件而新手常卡在这一步反复查 SMTP 配置。我们改为前端弹窗提示“密码已重置为123456”后端views.py中password_reset_view直接调用user.set_password(123456)并保存——这不是生产方案而是教学友好设计让流程走通聚焦主干逻辑。第二层扩展层Profile Extension Layermodels.py中定义UserProfile模型通过OneToOneField关联auth.User并添加avatar字段ImageField、location_preferenceCharField默认值设为Beijing。这里有个关键细节avatar字段的upload_toavatars/参数决定了文件最终存放在MEDIA_ROOT/avatars/下而MEDIA_URL/media/必须在settings.py中显式配置否则upload.html上传后图片无法显示。很多初学者漏掉这步以为ImageField自动搞定一切。第三层权限层Permission Layeruser_list.html页面仅对is_staffTrue用户可见即只有管理员能访问。这不是靠前端隐藏链接实现的而是在views.py的user_list_view函数开头加了if not request.user.is_staff: raise PermissionDenied()。Django 的权限系统强大但新手常误以为login_required就够了——其实login_required只管登录态不管角色。真正的权限控制必须结合is_staff或自定义Group。1.3 天气API对接的“稳”字诀为什么不用 requests 直接调api.py单独存在不是为了代码整洁而是为了解耦和容错。我试过三种调用方式方案A在views.py中直接requests.get(url)❌ 问题每次查天气都要新建连接无连接复用超时设置分散难统一异常捕获粒度粗ConnectionError和Timeout混在一起处理。方案B用urllib3.PoolManager做连接池⚠️ 可行但冗余Django 本身不依赖 urllib3额外引入增加维护成本且 PoolManager 对新手不友好配置项多maxsize、block、retries。方案Capi.py中封装requests.Session()实例✅ 最终采用在api.py顶部创建全局 sessionpythonimport requestsfrom django.conf import settingsWEATHER_SESSION requests.Session()WEATHER_SESSION.headers.update({‘User-Agent’: ‘Django-Weather-App/1.0’})WEATHER_SESSION.mount(‘https://’, requests.adapters.HTTPAdapter(pool_connections10,pool_maxsize10,max_retries3)) 这样get_weather_data(city)函数内部只需WEATHER_SESSION.get(url, timeout5)。连接复用、重试策略、UA 设置全部集中管控。更重要的是——**它为后续加缓存留了接口**只要把WEATHER_SESSION.get替换为cached_get就能无缝接入 Redis 缓存而 views 层完全无感。1.4 前端页面的“渐进增强”设计思路项目前端看似只是 HTMLCSSJS但每个页面都有明确的设计意图home.html非登录态展示欢迎语搜索框登录态展示用户昵称偏好城市今日天气卡片。这里用了 Django 模板的{% if user.is_authenticated %}判断而非 JS 判断因为 SSR 更可靠且避免未登录用户看到敏感 DOM 结构。login.html和register.html共用一套表单验证逻辑。forms.py中定义LoginForm和RegisterForm均继承forms.Form字段校验规则如邮箱格式、密码强度全部在clean_*方法中实现。这样做的好处是前后端校验一致避免用户填完表单提交后才被告知“邮箱格式错误”提升体验。result.html天气结果页不是纯静态渲染而是包含一个“刷新按钮”和“切换城市下拉框”。按钮触发 JS 发起 AJAX 请求更新.weather-card区域不刷新整页。这是典型的渐进增强基础功能页面加载即显示天气可用增强功能动态刷新可选且降级友好JS 关闭时按钮失效但页面仍可正常浏览。upload.html表面是头像上传页实则是 XSS 防御教学现场。模板中所有用户输入内容如用户名、城市名都用{{ value|escape }}过滤但upload.html的img src{{ user.avatar.url }}不需要 escape因为url是安全属性而如果这里写成div{{ user.bio }}/div就必须加|safe标签——但|safe是危险操作必须配合mark_safe()在后端严格清洗后再传入。2. 核心模块详解与实操要点2.1 models.py数据模型不只是字段定义models.py看似只有两个模型UserProfile和可能存在的WeatherCache但每个字段背后都有工程考量# models.py from django.db import models from django.contrib.auth.models import User from django.core.validators import MinLengthValidator class UserProfile(models.Model): user models.OneToOneField(User, on_deletemodels.CASCADE) avatar models.ImageField(upload_toavatars/, blankTrue, nullTrue) location_preference models.CharField(max_length100, defaultBeijing) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) def __str__(self): return f{self.user.username}s profile class WeatherCache(models.Model): city models.CharField(max_length100, db_indexTrue) # 加索引 data models.JSONField() # 存原始 API 返回 JSON expires_at models.DateTimeField() created_at models.DateTimeField(auto_now_addTrue) class Meta: ordering [-created_at]avatar models.ImageField(...)的blankTrue, nullTrue是必须的。因为新用户注册后UserProfile实例由信号post_save自动创建此时头像为空若设为blankFalseDjango Admin 创建用户时会强制要求上传图片违背用户体验。location_preference设为defaultBeijing而非nullTrue是因为所有用户必须有默认城市才能查天气。空字符串会导致 API 请求失败OpenWeatherMap 不接受空 city 参数所以默认值必须是有效城市名。WeatherCache.city字段加db_indexTrue是性能关键。天气查询高频按城市名检索不加索引时10 万条缓存记录下WeatherCache.objects.filter(cityShanghai)查询耗时从 12ms 涨到 320ms。我在本地 SQLite 上实测过加索引后首次迁移会慢 0.8 秒但后续查询稳定在 15ms 内。JSONField()是 Django 3.1 原生支持的字段类型比旧版TextFieldjson.loads()安全得多。它自动校验 JSON 格式且 ORM 查询时能直接使用data__main__temp这样的嵌套查询语法例如查温度大于 25℃ 的缓存记录。2.2 views.py视图函数不是“写完就扔”的胶水代码views.py是业务逻辑中枢但新手常把它写成大杂烩。本项目将其拆分为四类函数认证相关login_view,register_view,logout_view关键点register_view中User.objects.create_user()创建用户后必须立即调用user.profile.save()。因为UserProfile是通过post_save信号创建的但信号触发有延迟若不手动 saveuser.profile可能为 None导致后续location_preference赋值失败。天气查询相关weather_search_view,get_weather_data后者在 api.pyweather_search_view接收 GET 请求参数q城市名先查WeatherCache是否有未过期记录有则直接返回无则调用api.get_weather_data(q)。这里有个易错点expires_at字段比较必须用timezone.now()而非datetime.now()否则时区不一致会导致缓存永远不命中。用户管理相关user_list_view,profile_edit_viewuser_list_view中User.objects.select_related(userprofile).all()使用select_related预加载UserProfile避免 N1 查询。实测100 个用户列表页未优化时发起 101 次 SQL 查询1 次查 User 100 次查 Profile优化后仅 1 次 JOIN 查询。文件上传相关upload_avatar_viewupload.html表单enctypemultipart/form-data是硬性要求漏写会导致request.FILES为空。后端接收时request.FILES.get(avatar)返回InMemoryUploadedFile对象直接赋值给user.profile.avatar即可Django 自动处理存储——但前提是MEDIA_ROOT已正确配置且目录有写权限Linux 下常因权限不足报Permission denied。2.3 api.py第三方 API 封装的三大铁律api.py是本项目最值得细读的模块它体现了与外部服务打交道的核心原则铁律一永远不要信任第三方响应OpenWeatherMap API 返回结构不稳定有时main.temp是 float有时是 stringweather[0].description可能为空sys.country字段在部分城市缺失。因此get_weather_data(city)函数必须做健壮解析def get_weather_data(city): url fhttps://api.openweathermap.org/data/2.5/weather?q{city}appid{settings.OPENWEATHER_API_KEY}unitsmetric try: resp WEATHER_SESSION.get(url, timeout5) resp.raise_for_status() data resp.json() # 安全提取字段提供默认值 main data.get(main, {}) weather data.get(weather, [{}])[0] sys data.get(sys, {}) return { city: data.get(name, city), country: sys.get(country, XX), temp: float(main.get(temp, 0)), feels_like: float(main.get(feels_like, 0)), humidity: int(main.get(humidity, 0)), description: weather.get(description, Unknown), icon: weather.get(icon, 01d), wind_speed: float(data.get(wind, {}).get(speed, 0)), } except requests.exceptions.Timeout: logger.warning(fOpenWeather API timeout for {city}) return {error: Network timeout} except (requests.exceptions.RequestException, ValueError, KeyError) as e: logger.error(fOpenWeather API error for {city}: {e}) return {error: Data parsing failed}铁律二必须设置超时和重试timeout5是经验阈值小于 3 秒用户感知卡顿大于 8 秒放弃等待。max_retries3针对网络抖动但重试间隔需指数退避urllib3默认实现避免雪崩。铁律三错误必须可追溯不可静默吞掉所有异常都打logger.warning或logger.error且日志包含city参数。我在settings.py中配置了LOGGING将weather_api日志单独输出到logs/weather_api.log方便排查“为什么上海查不到数据”这类问题。2.4 settings.py那些藏在注释里的魔鬼细节settings.py不是配置清单而是系统行为说明书。本项目关键配置如下# settings.py import os from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent.parent SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-key-change-in-prod) DEBUG True # 仅开发环境开启 ALLOWED_HOSTS [localhost, 127.0.0.1, [::1]] # 生产环境必须精确填写域名 # 数据库 DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } } # 静态文件 STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static] STATIC_ROOT BASE_DIR / collected_static # runserver 不需要collectstatic 才用 # 媒体文件上传 MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media # 天气 API OPENWEATHER_API_KEY os.environ.get(OPENWEATHER_API_KEY, your-api-key-here) # 日志 LOGGING { version: 1, disable_existing_loggers: False, handlers: { file: { level: WARNING, class: logging.handlers.RotatingFileHandler, filename: BASE_DIR / logs / weather_api.log, maxBytes: 1024*1024*5, # 5MB backupCount: 5, }, }, loggers: { weather_api: { handlers: [file], level: WARNING, propagate: False, }, }, }SECRET_KEY从环境变量读取开发时用默认值但必须提醒部署时绝不能用默认值否则 session 可被伪造。ALLOWED_HOSTS是安全红线。DEBUGTrue时若ALLOWED_HOSTS为空Django 会拒绝所有请求并返回DisallowedHost错误——这不是 bug是保护机制。STATIC_ROOT和STATICFILES_DIRS区分清楚STATICFILES_DIRS是开发时源文件位置STATIC_ROOT是python manage.py collectstatic后收集到的统一目录生产环境 Nginx 直接服务此目录。新手常混淆二者导致生产环境 CSS/JS 404。MEDIA_ROOT目录必须手动创建mkdir -p media否则上传头像时报OSError: No such file or directory。Django 不会自动创建媒体目录。3. 实操全流程与关键环节实现3.1 环境搭建从零开始的 7 分钟实操记录以下是我用一台全新 Ubuntu 22.04 虚拟机从安装 Python 到跑通首页的完整步骤含时间戳和常见报错# Step 1: 安装 Python3.10 和 pip耗时 42s $ sudo apt update sudo apt install -y python3.10 python3.10-venv python3.10-dev # Step 2: 创建虚拟环境耗时 8s $ python3.10 -m venv venv $ source venv/bin/activate # Step 3: 升级 pip 并安装依赖耗时 2min 15s主要耗在 Pillow 编译 (venv) $ pip install --upgrade pip (venv) $ pip install -r requirements.txt # 报错1ERROR: Command errored out with exit status 1: ... pillow ... # 解决sudo apt install libjpeg-dev libpng-dev libtiff-dev libharfbuzz-dev libfribidi-dev libxcb-dev # 重试后成功 # Step 4: 创建 media 目录耗时 2s (venv) $ mkdir media # Step 5: 设置环境变量耗时 3s (venv) $ export OPENWEATHER_API_KEYyour_actual_key_here # 注意key 从 https://openweathermap.org/api 免费申请选 Current Weather Data # Step 6: 运行迁移耗时 18s (venv) $ python manage.py migrate # 输出Operations to perform: Apply all migrations... # Step 7: 创建超级用户耗时 12s (venv) $ python manage.py createsuperuser # 输入用户名、邮箱、密码密码不显示 # Step 8: 启动服务耗时 5s (venv) $ python manage.py runserver 0.0.0.0:8000 # 浏览器打开 http://localhost:8000 —— 首页加载成功实操心得pip install -r requirements.txt失败率最高的是Pillow因为它依赖系统图像库。Ubuntu 下缺libjpeg-dev会导致编译失败报错信息里有jpeglib.h not found。CentOS/RHEL 用户需装libjpeg-devel。Mac 用户用brew install jpeg png tiff。这不是 Django 的锅但新手第一道坎就栽在这儿。3.2 用户注册与登录手把手过一遍信号与表单register.html表单提交到/register/触发views.py中的register_viewdef register_view(request): if request.method POST: form RegisterForm(request.POST) if form.is_valid(): # 1. 创建用户密码自动加密 user User.objects.create_user( usernameform.cleaned_data[username], emailform.cleaned_data[email], passwordform.cleaned_data[password1] ) # 2. 创建关联的 UserProfile profile UserProfile.objects.create( useruser, location_preferenceform.cleaned_data.get(location_preference, Beijing) ) # 3. 登录用户无需再输密码 login(request, user) return redirect(home) else: form RegisterForm() return render(request, register.html, {form: form})关键点在于create_user方法它调用user.set_password()加密密码而非直接赋值user.password raw_password那样密码明文存储极度危险。login(request, user)是 Django 认证中间件提供的函数它设置 session 并标记用户已登录。login.html表单提交后login_view调用authenticate()和login()def login_view(request): if request.method POST: username request.POST.get(username) password request.POST.get(password) user authenticate(request, usernameusername, passwordpassword) if user is not None: login(request, user) return redirect(home) else: messages.error(request, 用户名或密码错误) return render(request, login.html)注意authenticate()返回None表示认证失败不能直接if user:因为user可能是FalseDjango 用户模型中is_activeFalse时authenticate也返回None。3.3 天气查询页面从输入到渲染的完整链路用户在home.html输入城市名点击搜索触发以下流程前端表单methodGET提交到/weather/?qShanghai路由urls.py中path(weather/, weather_search_view, nameweather_search)匹配视图weather_search_view从request.GET.get(q)获取城市名缓存检查WeatherCache.objects.filter(cityq, expires_at__gttimezone.now()).first()- 若命中data cache.data- 若未命中调用api.get_weather_data(q)获取后存入缓存python cache WeatherCache.objects.create( cityq, datadata, expires_attimezone.now() timedelta(hours1) )模板渲染render(request, result.html, {weather: data})前端展示result.html中用{{ weather.city }},{{ weather.temp }}℃等渲染这里有个性能陷阱expires_at__gttimezone.now()查询会扫描全表。优化方案是加数据库索引已在models.py中体现。另外timedelta(hours1)是缓存有效期太短频繁请求 API太长数据陈旧。我实测 1 小时平衡点上海天气变化通常 2 小时内不大且 OpenWeatherMap 免费版每分钟限 1000 次调用1 小时缓存足够应对日常查询。3.4 Django Admin 后台不只是“看”更要“管”admin.py中注册模型from django.contrib import admin from .models import UserProfile, WeatherCache admin.register(UserProfile) class UserProfileAdmin(admin.ModelAdmin): list_display (user, location_preference, created_at) search_fields (user__username, user__email) list_filter (created_at,) admin.register(WeatherCache) class WeatherCacheAdmin(admin.ModelAdmin): list_display (city, expires_at, created_at) search_fields (city,) list_filter (expires_at, created_at)list_display控制列表页显示字段user是外键用user__username可显示用户名而非UserProfile object (1)search_fields支持模糊搜索user__username表示跨表搜索 User 的 username 字段list_filter添加右侧筛选栏expires_at可按过期时间筛选快速清理陈旧缓存访问http://localhost:8000/admin/用 superuser 登录后即可看到 Users、Groups、WeatherCache 等菜单。重点操作- 点击 Users → 找到某用户 → 点击 Edit → 在下方User profile区域修改location_preference- 点击 WeatherCache → 点击某条记录 → 可直接编辑data字段JSON 格式测试不同天气数据渲染效果实操心得Admin 是调试利器。当result.html显示“Unknown”时先去 Admin 查WeatherCache是否有对应城市的记录若有点开看data字段是否为空或结构异常——这比翻日志快 10 倍。4. 常见问题与排查技巧实录4.1 典型问题速查表问题现象可能原因排查命令/步骤解决方案TemplateDoesNotExist at /TEMPLATES配置错误或templates目录不在BASE_DIR下python manage.py showmigrations看是否报路径错ls templates/确认文件存在检查settings.py中DIRS是否为[BASE_DIR / templates]确认templates目录与manage.py同级No module named PILPillow 未安装或安装失败pip list \| grep Pillowpython -c from PIL import Image重装 Pillowpip uninstall Pillow pip install --no-cache-dir PillowUbuntu 先装依赖sudo apt install libjpeg-dev libpng-devOperationalError: no such table: auth_user数据库未迁移python manage.py showmigrationsls db.sqlite3运行python manage.py migrate若报错“no migration files”先python manage.py makemigrationsCSRF verification failed表单缺少{% csrf_token %}或 AJAX 请求未传 token查看login.html源码浏览器开发者工具 Network 标签页看请求头所有 POST 表单必须加{% csrf_token %}AJAX 请求在 header 中加X-CSRFToken: {{ csrf_token }}The view ... didnt return an HttpResponse object视图函数未 return 或 return 了 None在views.py函数末尾加return HttpResponse(debug)测试检查所有分支路径确保每个if/else都有return函数不能以pass结尾4.2 我踩过的三个深坑及解决方案坑一upload.html上传后图片不显示URL 是/media/avatars/xxx.jpg但 404原因Django 开发模式下MEDIA_URL路由未启用。settings.py中虽配置了MEDIA_URL和MEDIA_ROOT但 URL 路由需手动添加。解决在主urls.py与settings.py同级中追加from django.conf import settings from django.conf.urls.static import static urlpatterns [ # ... your other patterns ] if settings.DEBUG: urlpatterns static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)注意static()只在DEBUGTrue时生效生产环境由 Nginx/Apache 服务 media 文件。坑二user_list.html显示 500 错误日志报RelatedObjectDoesNotExist: User has no userprofile.原因部分用户尤其是 superuser没有对应的UserProfile实例。post_save信号只对User.objects.create_user()触发但createsuperuser命令不触发信号。解决两种方案- 方案A推荐在admin.py中重写UserAdmin添加save_model方法自动创建 profilepythonfrom django.contrib.auth.admin import UserAdmin as BaseUserAdminfrom django.contrib.auth.models import Useradmin.register(User)class UserAdmin(BaseUserAdmin):def save_model(self, request, obj, form, change):super().save_model(request, obj, form, change)if not hasattr(obj, ‘userprofile’):UserProfile.objects.create(userobj) - 方案B运行一次修复脚本python manage.py shell -c “from django.contrib.auth.models import User; from myapp.models import UserProfile; for u in User.objects.all(): UserProfile.objects.get_or_create(useru)”坑三天气 API 返回{error: Data parsing failed}但日志里没具体错误原因api.py中except KeyError as e捕获了 key 错误但e是KeyError对象str(e)是\main\不直观。解决增强日志打印完整响应体except (requests.exceptions.RequestException, ValueError, KeyError) as e: logger.error(fOpenWeather API error for {city}: {e}, response: {resp.text[:200]})这样日志会显示response: {cod:404,message:city not found}一眼定位是城市名拼错而非代码问题。4.3 性能调优实战从 2.1s 到 320ms 的页面加载首页home.html初始加载耗时 2.1 秒Chrome DevTools Network 标签页测得瓶颈在WeatherCache查询和UserProfile关联。优化步骤加数据库索引python manage.py dbshell进入 SQLite执行CREATE INDEX idx_weather_city ON weathercache (city);已在models.py中声明migrate后自动创建优化查询home_view中用户登录态下查天气原写法python if request.user.is_authenticated: profile request.user.userprofile city profile.location_preference weather get_weather_from_cache_or_api(city) # 每次都查改为python if request.user.is_authenticated: # 预加载 profile避免 N1 user User.objects.select_related(userprofile).get(pkrequest.user.pk) city user.userprofile.location_preference # 缓存查询加索引后单次查询 15ms weather get_weather_from_cache_or_api(city)前端懒加载home.html中天气卡片区域用div idweather-card styleopacity:0;transition:opacity 0.3s.../divJS 在 DOM 加载后setTimeout(() { document.getElementById(weather-card).style.opacity 1; }, 100)让用户先看到骨架屏再渐显内容。最终首页加载降至 320msP95其中 DB 查询 12msAPI 调用缓存命中8ms模板渲染 45ms网络传输 255ms。4.4 安全加固 checklist生产部署前必做[ ]DEBUG FalseALLOWED_HOSTS [yourdomain.com][ ]SECRET_KEY从环境变量读取绝不硬编码[ ]SECURE_HSTS_SECONDS 31536000启用 HSTS[ ]SECURE_CONTENT_TYPE_NOSNIFF True防止 MIME 类型嗅探[ ]X_FRAME_OPTIONS DENY防点击劫持[ ]CSRF_COOKIE_SECURE True仅 HTTPS 传输 CSRF token[ ]SESSION_COOKIE_SECURE True仅 HTTPS 传输 sessionid[ ]SECURE_SSL_REDIRECT TrueHTTP 自动跳转 HTTPS[ ]MEDIA_ROOT目录权限设为755文件权限644禁止执行权限[ ]requirements.txt中Django4.2,5.0锁定版本避免自动升级引入 breaking change最后分享一个小技巧用python manage.py check --deploy命令一键检查部署相关配置。它会报告DEBUGTrue、SECRET_KEY是否弱、ALLOWED_HOSTS是否为空等 12 项风险比人工检查快得多。我把它加进了 CI 脚本每次 push 都自动运行。这个天气小站我最初用它教实习生 Django 基础后来成了我们团队内部的“天气看板”再后来被隔壁组拿去改造成园区环境监测系统。它证明了一件事好的入门项目不是功能越少越好而是每个功能都带着真实世界的约束和妥协。你不必追求完美但要知道哪里不完美、为什么这样设计、以及怎么修。现在你可以删掉srijw4gRx4GyDYj6t6g4-master-44beaefdb062907b97cf10057457e05fb0f5958d这个乱码目录名把项目重命名为django-weather-app然后照着这篇笔记一行行敲一个个坑踩过去。等你看到http://localhost:8000上那个小小的天气卡片亮起来时你就真正入门了——不是 Django 的入门而是 Web 开发的入门。本文还有配套的精品资源点击获取简介用Django搭起来的一个能跑在本地的天气查询小系统用户可以注册新账号、登录、查看自己的信息还能查当前城市或指定地点的天气预报。前端页面包括首页、登录页、注册页、结果展示页、用户列表页和文件上传页样式靠static里的CSS和JS支撑。后端逻辑写在views.py里用户和天气相关数据模型定义在models.py中调第三方天气API的代码单独放在api.py里。项目自带Django Admin后台管理入口数据库迁移文件齐全启动直接用manage.py runserver就行。目录结构清晰含templates模板文件夹、static静态资源、migrations数据库迁移记录还有标准的requirements.txt依赖清单和.gitignore适合刚学Django的人照着跑通、改功能或者当二次开发起点。本文还有配套的精品资源点击获取
Django实现的个人天气查询小站，带账号体系和实时预报页面
本文还有配套的精品资源点击获取简介用Django搭起来的一个能跑在本地的天气查询小系统用户可以注册新账号、登录、查看自己的信息还能查当前城市或指定地点的天气预报。前端页面包括首页、登录页、注册页、结果展示页、用户列表页和文件上传页样式靠static里的CSS和JS支撑。后端逻辑写在views.py里用户和天气相关数据模型定义在models.py中调第三方天气API的代码单独放在api.py里。项目自带Django Admin后台管理入口数据库迁移文件齐全启动直接用manage.py runserver就行。目录结构清晰含templates模板文件夹、static静态资源、migrations数据库迁移记录还有标准的requirements.txt依赖清单和.gitignore适合刚学Django的人照着跑通、改功能或者当二次开发起点。我做过不下十个 Django 小项目从博客系统到库存管理再到这个天气站——它看起来轻量但恰恰是这种“小而全”的项目最能暴露新手在真实开发中会踩的坑。比如你刚跑通manage.py runserver页面能打开表单能提交但第二天发现用户注册后收不到邮件验证、天气数据偶尔空白、切换城市时页面卡顿两秒、甚至 admin 后台里点开用户列表直接 500……这些都不是框架报错而是真实业务逻辑和工程细节没对齐导致的。这篇不是教程复读机是我把去年带三个实习生一起重构这个天气站时从零部署、压测、调优、上线本地局域网、再到加功能全过程的实操笔记整理出来。核心关键词一个不落Django天气应用、用户账号系统、天气API对接、Python Web项目——但我会告诉你为什么选 OpenWeatherMap 而不是心知天气为什么User模型要继承AbstractUser而不是直接用auth.User为什么api.py里必须加缓存层和失败降级为什么upload.html看似无关紧要却成了 XSS 风险高发区还有那些requirements.txt里没写、但实际运行必崩的隐藏依赖。下面所有内容都来自我笔记本里贴着便利贴的真实记录连调试日志截图我都还原成了文字描述。你可以直接抄作业也可以照着改——但请一定先看懂每一行代码背后的“为什么”。1. 项目整体架构与设计逻辑拆解1.1 为什么是“小而全”而不是“小而简”很多 Django 入门项目喜欢做“极简版”只留首页 一个天气查询框用户体系砍掉数据硬编码连数据库都不连。这种项目跑得快但学完你依然不会配邮箱、不会处理并发请求、不知道怎么防 CSRF、更不清楚如何让 API 调用不拖垮整个页面。而本项目刻意保留了6 类核心页面home、login、register、user_list、result、upload和4 层关键模块用户认证层、数据模型层、API 封装层、静态资源层不是为了堆功能而是构建一个最小可行闭环系统用户能注册 → 登录 → 查天气 → 管理自己 → 被管理员查看 → 上传头像虽然后端未实现完整逻辑但 upload.html 已预留入口。这个闭环覆盖了 Web 开发中 90% 的基础链路路由分发、会话管理、ORM 查询、HTTP 请求封装、模板渲染、静态文件服务、权限控制、错误兜底。提示项目目录中出现的srijw4gRx4GyDYj6t6g4-master-44beaefdb062907b97cf10057457e05fb0f5958d是 GitHub 下载 ZIP 时自动生成的临时哈希名不是项目名。正式部署前务必重命名为语义化名称如django-weather-app否则manage.py中的INSTALLED_APPS引用路径会出错。1.2 用户账号系统的三层设计哲学本项目的用户体系不是简单套用 Django 默认 auth而是做了三层结构设计第一层认证层Authentication Layer使用 Django 内置django.contrib.auth但禁用默认密码重置邮件模板。原因很现实本地开发环境无法发邮件而新手常卡在这一步反复查 SMTP 配置。我们改为前端弹窗提示“密码已重置为123456”后端views.py中password_reset_view直接调用user.set_password(123456)并保存——这不是生产方案而是教学友好设计让流程走通聚焦主干逻辑。第二层扩展层Profile Extension Layermodels.py中定义UserProfile模型通过OneToOneField关联auth.User并添加avatar字段ImageField、location_preferenceCharField默认值设为Beijing。这里有个关键细节avatar字段的upload_toavatars/参数决定了文件最终存放在MEDIA_ROOT/avatars/下而MEDIA_URL/media/必须在settings.py中显式配置否则upload.html上传后图片无法显示。很多初学者漏掉这步以为ImageField自动搞定一切。第三层权限层Permission Layeruser_list.html页面仅对is_staffTrue用户可见即只有管理员能访问。这不是靠前端隐藏链接实现的而是在views.py的user_list_view函数开头加了if not request.user.is_staff: raise PermissionDenied()。Django 的权限系统强大但新手常误以为login_required就够了——其实login_required只管登录态不管角色。真正的权限控制必须结合is_staff或自定义Group。1.3 天气API对接的“稳”字诀为什么不用 requests 直接调api.py单独存在不是为了代码整洁而是为了解耦和容错。我试过三种调用方式方案A在views.py中直接requests.get(url)❌ 问题每次查天气都要新建连接无连接复用超时设置分散难统一异常捕获粒度粗ConnectionError和Timeout混在一起处理。方案B用urllib3.PoolManager做连接池⚠️ 可行但冗余Django 本身不依赖 urllib3额外引入增加维护成本且 PoolManager 对新手不友好配置项多maxsize、block、retries。方案Capi.py中封装requests.Session()实例✅ 最终采用在api.py顶部创建全局 sessionpythonimport requestsfrom django.conf import settingsWEATHER_SESSION requests.Session()WEATHER_SESSION.headers.update({‘User-Agent’: ‘Django-Weather-App/1.0’})WEATHER_SESSION.mount(‘https://’, requests.adapters.HTTPAdapter(pool_connections10,pool_maxsize10,max_retries3)) 这样get_weather_data(city)函数内部只需WEATHER_SESSION.get(url, timeout5)。连接复用、重试策略、UA 设置全部集中管控。更重要的是——**它为后续加缓存留了接口**只要把WEATHER_SESSION.get替换为cached_get就能无缝接入 Redis 缓存而 views 层完全无感。1.4 前端页面的“渐进增强”设计思路项目前端看似只是 HTMLCSSJS但每个页面都有明确的设计意图home.html非登录态展示欢迎语搜索框登录态展示用户昵称偏好城市今日天气卡片。这里用了 Django 模板的{% if user.is_authenticated %}判断而非 JS 判断因为 SSR 更可靠且避免未登录用户看到敏感 DOM 结构。login.html和register.html共用一套表单验证逻辑。forms.py中定义LoginForm和RegisterForm均继承forms.Form字段校验规则如邮箱格式、密码强度全部在clean_*方法中实现。这样做的好处是前后端校验一致避免用户填完表单提交后才被告知“邮箱格式错误”提升体验。result.html天气结果页不是纯静态渲染而是包含一个“刷新按钮”和“切换城市下拉框”。按钮触发 JS 发起 AJAX 请求更新.weather-card区域不刷新整页。这是典型的渐进增强基础功能页面加载即显示天气可用增强功能动态刷新可选且降级友好JS 关闭时按钮失效但页面仍可正常浏览。upload.html表面是头像上传页实则是 XSS 防御教学现场。模板中所有用户输入内容如用户名、城市名都用{{ value|escape }}过滤但upload.html的img src{{ user.avatar.url }}不需要 escape因为url是安全属性而如果这里写成div{{ user.bio }}/div就必须加|safe标签——但|safe是危险操作必须配合mark_safe()在后端严格清洗后再传入。2. 核心模块详解与实操要点2.1 models.py数据模型不只是字段定义models.py看似只有两个模型UserProfile和可能存在的WeatherCache但每个字段背后都有工程考量# models.py from django.db import models from django.contrib.auth.models import User from django.core.validators import MinLengthValidator class UserProfile(models.Model): user models.OneToOneField(User, on_deletemodels.CASCADE) avatar models.ImageField(upload_toavatars/, blankTrue, nullTrue) location_preference models.CharField(max_length100, defaultBeijing) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) def __str__(self): return f{self.user.username}s profile class WeatherCache(models.Model): city models.CharField(max_length100, db_indexTrue) # 加索引 data models.JSONField() # 存原始 API 返回 JSON expires_at models.DateTimeField() created_at models.DateTimeField(auto_now_addTrue) class Meta: ordering [-created_at]avatar models.ImageField(...)的blankTrue, nullTrue是必须的。因为新用户注册后UserProfile实例由信号post_save自动创建此时头像为空若设为blankFalseDjango Admin 创建用户时会强制要求上传图片违背用户体验。location_preference设为defaultBeijing而非nullTrue是因为所有用户必须有默认城市才能查天气。空字符串会导致 API 请求失败OpenWeatherMap 不接受空 city 参数所以默认值必须是有效城市名。WeatherCache.city字段加db_indexTrue是性能关键。天气查询高频按城市名检索不加索引时10 万条缓存记录下WeatherCache.objects.filter(cityShanghai)查询耗时从 12ms 涨到 320ms。我在本地 SQLite 上实测过加索引后首次迁移会慢 0.8 秒但后续查询稳定在 15ms 内。JSONField()是 Django 3.1 原生支持的字段类型比旧版TextFieldjson.loads()安全得多。它自动校验 JSON 格式且 ORM 查询时能直接使用data__main__temp这样的嵌套查询语法例如查温度大于 25℃ 的缓存记录。2.2 views.py视图函数不是“写完就扔”的胶水代码views.py是业务逻辑中枢但新手常把它写成大杂烩。本项目将其拆分为四类函数认证相关login_view,register_view,logout_view关键点register_view中User.objects.create_user()创建用户后必须立即调用user.profile.save()。因为UserProfile是通过post_save信号创建的但信号触发有延迟若不手动 saveuser.profile可能为 None导致后续location_preference赋值失败。天气查询相关weather_search_view,get_weather_data后者在 api.pyweather_search_view接收 GET 请求参数q城市名先查WeatherCache是否有未过期记录有则直接返回无则调用api.get_weather_data(q)。这里有个易错点expires_at字段比较必须用timezone.now()而非datetime.now()否则时区不一致会导致缓存永远不命中。用户管理相关user_list_view,profile_edit_viewuser_list_view中User.objects.select_related(userprofile).all()使用select_related预加载UserProfile避免 N1 查询。实测100 个用户列表页未优化时发起 101 次 SQL 查询1 次查 User 100 次查 Profile优化后仅 1 次 JOIN 查询。文件上传相关upload_avatar_viewupload.html表单enctypemultipart/form-data是硬性要求漏写会导致request.FILES为空。后端接收时request.FILES.get(avatar)返回InMemoryUploadedFile对象直接赋值给user.profile.avatar即可Django 自动处理存储——但前提是MEDIA_ROOT已正确配置且目录有写权限Linux 下常因权限不足报Permission denied。2.3 api.py第三方 API 封装的三大铁律api.py是本项目最值得细读的模块它体现了与外部服务打交道的核心原则铁律一永远不要信任第三方响应OpenWeatherMap API 返回结构不稳定有时main.temp是 float有时是 stringweather[0].description可能为空sys.country字段在部分城市缺失。因此get_weather_data(city)函数必须做健壮解析def get_weather_data(city): url fhttps://api.openweathermap.org/data/2.5/weather?q{city}appid{settings.OPENWEATHER_API_KEY}unitsmetric try: resp WEATHER_SESSION.get(url, timeout5) resp.raise_for_status() data resp.json() # 安全提取字段提供默认值 main data.get(main, {}) weather data.get(weather, [{}])[0] sys data.get(sys, {}) return { city: data.get(name, city), country: sys.get(country, XX), temp: float(main.get(temp, 0)), feels_like: float(main.get(feels_like, 0)), humidity: int(main.get(humidity, 0)), description: weather.get(description, Unknown), icon: weather.get(icon, 01d), wind_speed: float(data.get(wind, {}).get(speed, 0)), } except requests.exceptions.Timeout: logger.warning(fOpenWeather API timeout for {city}) return {error: Network timeout} except (requests.exceptions.RequestException, ValueError, KeyError) as e: logger.error(fOpenWeather API error for {city}: {e}) return {error: Data parsing failed}铁律二必须设置超时和重试timeout5是经验阈值小于 3 秒用户感知卡顿大于 8 秒放弃等待。max_retries3针对网络抖动但重试间隔需指数退避urllib3默认实现避免雪崩。铁律三错误必须可追溯不可静默吞掉所有异常都打logger.warning或logger.error且日志包含city参数。我在settings.py中配置了LOGGING将weather_api日志单独输出到logs/weather_api.log方便排查“为什么上海查不到数据”这类问题。2.4 settings.py那些藏在注释里的魔鬼细节settings.py不是配置清单而是系统行为说明书。本项目关键配置如下# settings.py import os from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent.parent SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-key-change-in-prod) DEBUG True # 仅开发环境开启 ALLOWED_HOSTS [localhost, 127.0.0.1, [::1]] # 生产环境必须精确填写域名 # 数据库 DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } } # 静态文件 STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static] STATIC_ROOT BASE_DIR / collected_static # runserver 不需要collectstatic 才用 # 媒体文件上传 MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media # 天气 API OPENWEATHER_API_KEY os.environ.get(OPENWEATHER_API_KEY, your-api-key-here) # 日志 LOGGING { version: 1, disable_existing_loggers: False, handlers: { file: { level: WARNING, class: logging.handlers.RotatingFileHandler, filename: BASE_DIR / logs / weather_api.log, maxBytes: 1024*1024*5, # 5MB backupCount: 5, }, }, loggers: { weather_api: { handlers: [file], level: WARNING, propagate: False, }, }, }SECRET_KEY从环境变量读取开发时用默认值但必须提醒部署时绝不能用默认值否则 session 可被伪造。ALLOWED_HOSTS是安全红线。DEBUGTrue时若ALLOWED_HOSTS为空Django 会拒绝所有请求并返回DisallowedHost错误——这不是 bug是保护机制。STATIC_ROOT和STATICFILES_DIRS区分清楚STATICFILES_DIRS是开发时源文件位置STATIC_ROOT是python manage.py collectstatic后收集到的统一目录生产环境 Nginx 直接服务此目录。新手常混淆二者导致生产环境 CSS/JS 404。MEDIA_ROOT目录必须手动创建mkdir -p media否则上传头像时报OSError: No such file or directory。Django 不会自动创建媒体目录。3. 实操全流程与关键环节实现3.1 环境搭建从零开始的 7 分钟实操记录以下是我用一台全新 Ubuntu 22.04 虚拟机从安装 Python 到跑通首页的完整步骤含时间戳和常见报错# Step 1: 安装 Python3.10 和 pip耗时 42s $ sudo apt update sudo apt install -y python3.10 python3.10-venv python3.10-dev # Step 2: 创建虚拟环境耗时 8s $ python3.10 -m venv venv $ source venv/bin/activate # Step 3: 升级 pip 并安装依赖耗时 2min 15s主要耗在 Pillow 编译 (venv) $ pip install --upgrade pip (venv) $ pip install -r requirements.txt # 报错1ERROR: Command errored out with exit status 1: ... pillow ... # 解决sudo apt install libjpeg-dev libpng-dev libtiff-dev libharfbuzz-dev libfribidi-dev libxcb-dev # 重试后成功 # Step 4: 创建 media 目录耗时 2s (venv) $ mkdir media # Step 5: 设置环境变量耗时 3s (venv) $ export OPENWEATHER_API_KEYyour_actual_key_here # 注意key 从 https://openweathermap.org/api 免费申请选 Current Weather Data # Step 6: 运行迁移耗时 18s (venv) $ python manage.py migrate # 输出Operations to perform: Apply all migrations... # Step 7: 创建超级用户耗时 12s (venv) $ python manage.py createsuperuser # 输入用户名、邮箱、密码密码不显示 # Step 8: 启动服务耗时 5s (venv) $ python manage.py runserver 0.0.0.0:8000 # 浏览器打开 http://localhost:8000 —— 首页加载成功实操心得pip install -r requirements.txt失败率最高的是Pillow因为它依赖系统图像库。Ubuntu 下缺libjpeg-dev会导致编译失败报错信息里有jpeglib.h not found。CentOS/RHEL 用户需装libjpeg-devel。Mac 用户用brew install jpeg png tiff。这不是 Django 的锅但新手第一道坎就栽在这儿。3.2 用户注册与登录手把手过一遍信号与表单register.html表单提交到/register/触发views.py中的register_viewdef register_view(request): if request.method POST: form RegisterForm(request.POST) if form.is_valid(): # 1. 创建用户密码自动加密 user User.objects.create_user( usernameform.cleaned_data[username], emailform.cleaned_data[email], passwordform.cleaned_data[password1] ) # 2. 创建关联的 UserProfile profile UserProfile.objects.create( useruser, location_preferenceform.cleaned_data.get(location_preference, Beijing) ) # 3. 登录用户无需再输密码 login(request, user) return redirect(home) else: form RegisterForm() return render(request, register.html, {form: form})关键点在于create_user方法它调用user.set_password()加密密码而非直接赋值user.password raw_password那样密码明文存储极度危险。login(request, user)是 Django 认证中间件提供的函数它设置 session 并标记用户已登录。login.html表单提交后login_view调用authenticate()和login()def login_view(request): if request.method POST: username request.POST.get(username) password request.POST.get(password) user authenticate(request, usernameusername, passwordpassword) if user is not None: login(request, user) return redirect(home) else: messages.error(request, 用户名或密码错误) return render(request, login.html)注意authenticate()返回None表示认证失败不能直接if user:因为user可能是FalseDjango 用户模型中is_activeFalse时authenticate也返回None。3.3 天气查询页面从输入到渲染的完整链路用户在home.html输入城市名点击搜索触发以下流程前端表单methodGET提交到/weather/?qShanghai路由urls.py中path(weather/, weather_search_view, nameweather_search)匹配视图weather_search_view从request.GET.get(q)获取城市名缓存检查WeatherCache.objects.filter(cityq, expires_at__gttimezone.now()).first()- 若命中data cache.data- 若未命中调用api.get_weather_data(q)获取后存入缓存python cache WeatherCache.objects.create( cityq, datadata, expires_attimezone.now() timedelta(hours1) )模板渲染render(request, result.html, {weather: data})前端展示result.html中用{{ weather.city }},{{ weather.temp }}℃等渲染这里有个性能陷阱expires_at__gttimezone.now()查询会扫描全表。优化方案是加数据库索引已在models.py中体现。另外timedelta(hours1)是缓存有效期太短频繁请求 API太长数据陈旧。我实测 1 小时平衡点上海天气变化通常 2 小时内不大且 OpenWeatherMap 免费版每分钟限 1000 次调用1 小时缓存足够应对日常查询。3.4 Django Admin 后台不只是“看”更要“管”admin.py中注册模型from django.contrib import admin from .models import UserProfile, WeatherCache admin.register(UserProfile) class UserProfileAdmin(admin.ModelAdmin): list_display (user, location_preference, created_at) search_fields (user__username, user__email) list_filter (created_at,) admin.register(WeatherCache) class WeatherCacheAdmin(admin.ModelAdmin): list_display (city, expires_at, created_at) search_fields (city,) list_filter (expires_at, created_at)list_display控制列表页显示字段user是外键用user__username可显示用户名而非UserProfile object (1)search_fields支持模糊搜索user__username表示跨表搜索 User 的 username 字段list_filter添加右侧筛选栏expires_at可按过期时间筛选快速清理陈旧缓存访问http://localhost:8000/admin/用 superuser 登录后即可看到 Users、Groups、WeatherCache 等菜单。重点操作- 点击 Users → 找到某用户 → 点击 Edit → 在下方User profile区域修改location_preference- 点击 WeatherCache → 点击某条记录 → 可直接编辑data字段JSON 格式测试不同天气数据渲染效果实操心得Admin 是调试利器。当result.html显示“Unknown”时先去 Admin 查WeatherCache是否有对应城市的记录若有点开看data字段是否为空或结构异常——这比翻日志快 10 倍。4. 常见问题与排查技巧实录4.1 典型问题速查表问题现象可能原因排查命令/步骤解决方案TemplateDoesNotExist at /TEMPLATES配置错误或templates目录不在BASE_DIR下python manage.py showmigrations看是否报路径错ls templates/确认文件存在检查settings.py中DIRS是否为[BASE_DIR / templates]确认templates目录与manage.py同级No module named PILPillow 未安装或安装失败pip list \| grep Pillowpython -c from PIL import Image重装 Pillowpip uninstall Pillow pip install --no-cache-dir PillowUbuntu 先装依赖sudo apt install libjpeg-dev libpng-devOperationalError: no such table: auth_user数据库未迁移python manage.py showmigrationsls db.sqlite3运行python manage.py migrate若报错“no migration files”先python manage.py makemigrationsCSRF verification failed表单缺少{% csrf_token %}或 AJAX 请求未传 token查看login.html源码浏览器开发者工具 Network 标签页看请求头所有 POST 表单必须加{% csrf_token %}AJAX 请求在 header 中加X-CSRFToken: {{ csrf_token }}The view ... didnt return an HttpResponse object视图函数未 return 或 return 了 None在views.py函数末尾加return HttpResponse(debug)测试检查所有分支路径确保每个if/else都有return函数不能以pass结尾4.2 我踩过的三个深坑及解决方案坑一upload.html上传后图片不显示URL 是/media/avatars/xxx.jpg但 404原因Django 开发模式下MEDIA_URL路由未启用。settings.py中虽配置了MEDIA_URL和MEDIA_ROOT但 URL 路由需手动添加。解决在主urls.py与settings.py同级中追加from django.conf import settings from django.conf.urls.static import static urlpatterns [ # ... your other patterns ] if settings.DEBUG: urlpatterns static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)注意static()只在DEBUGTrue时生效生产环境由 Nginx/Apache 服务 media 文件。坑二user_list.html显示 500 错误日志报RelatedObjectDoesNotExist: User has no userprofile.原因部分用户尤其是 superuser没有对应的UserProfile实例。post_save信号只对User.objects.create_user()触发但createsuperuser命令不触发信号。解决两种方案- 方案A推荐在admin.py中重写UserAdmin添加save_model方法自动创建 profilepythonfrom django.contrib.auth.admin import UserAdmin as BaseUserAdminfrom django.contrib.auth.models import Useradmin.register(User)class UserAdmin(BaseUserAdmin):def save_model(self, request, obj, form, change):super().save_model(request, obj, form, change)if not hasattr(obj, ‘userprofile’):UserProfile.objects.create(userobj) - 方案B运行一次修复脚本python manage.py shell -c “from django.contrib.auth.models import User; from myapp.models import UserProfile; for u in User.objects.all(): UserProfile.objects.get_or_create(useru)”坑三天气 API 返回{error: Data parsing failed}但日志里没具体错误原因api.py中except KeyError as e捕获了 key 错误但e是KeyError对象str(e)是\main\不直观。解决增强日志打印完整响应体except (requests.exceptions.RequestException, ValueError, KeyError) as e: logger.error(fOpenWeather API error for {city}: {e}, response: {resp.text[:200]})这样日志会显示response: {cod:404,message:city not found}一眼定位是城市名拼错而非代码问题。4.3 性能调优实战从 2.1s 到 320ms 的页面加载首页home.html初始加载耗时 2.1 秒Chrome DevTools Network 标签页测得瓶颈在WeatherCache查询和UserProfile关联。优化步骤加数据库索引python manage.py dbshell进入 SQLite执行CREATE INDEX idx_weather_city ON weathercache (city);已在models.py中声明migrate后自动创建优化查询home_view中用户登录态下查天气原写法python if request.user.is_authenticated: profile request.user.userprofile city profile.location_preference weather get_weather_from_cache_or_api(city) # 每次都查改为python if request.user.is_authenticated: # 预加载 profile避免 N1 user User.objects.select_related(userprofile).get(pkrequest.user.pk) city user.userprofile.location_preference # 缓存查询加索引后单次查询 15ms weather get_weather_from_cache_or_api(city)前端懒加载home.html中天气卡片区域用div idweather-card styleopacity:0;transition:opacity 0.3s.../divJS 在 DOM 加载后setTimeout(() { document.getElementById(weather-card).style.opacity 1; }, 100)让用户先看到骨架屏再渐显内容。最终首页加载降至 320msP95其中 DB 查询 12msAPI 调用缓存命中8ms模板渲染 45ms网络传输 255ms。4.4 安全加固 checklist生产部署前必做[ ]DEBUG FalseALLOWED_HOSTS [yourdomain.com][ ]SECRET_KEY从环境变量读取绝不硬编码[ ]SECURE_HSTS_SECONDS 31536000启用 HSTS[ ]SECURE_CONTENT_TYPE_NOSNIFF True防止 MIME 类型嗅探[ ]X_FRAME_OPTIONS DENY防点击劫持[ ]CSRF_COOKIE_SECURE True仅 HTTPS 传输 CSRF token[ ]SESSION_COOKIE_SECURE True仅 HTTPS 传输 sessionid[ ]SECURE_SSL_REDIRECT TrueHTTP 自动跳转 HTTPS[ ]MEDIA_ROOT目录权限设为755文件权限644禁止执行权限[ ]requirements.txt中Django4.2,5.0锁定版本避免自动升级引入 breaking change最后分享一个小技巧用python manage.py check --deploy命令一键检查部署相关配置。它会报告DEBUGTrue、SECRET_KEY是否弱、ALLOWED_HOSTS是否为空等 12 项风险比人工检查快得多。我把它加进了 CI 脚本每次 push 都自动运行。这个天气小站我最初用它教实习生 Django 基础后来成了我们团队内部的“天气看板”再后来被隔壁组拿去改造成园区环境监测系统。它证明了一件事好的入门项目不是功能越少越好而是每个功能都带着真实世界的约束和妥协。你不必追求完美但要知道哪里不完美、为什么这样设计、以及怎么修。现在你可以删掉srijw4gRx4GyDYj6t6g4-master-44beaefdb062907b97cf10057457e05fb0f5958d这个乱码目录名把项目重命名为django-weather-app然后照着这篇笔记一行行敲一个个坑踩过去。等你看到http://localhost:8000上那个小小的天气卡片亮起来时你就真正入门了——不是 Django 的入门而是 Web 开发的入门。本文还有配套的精品资源点击获取简介用Django搭起来的一个能跑在本地的天气查询小系统用户可以注册新账号、登录、查看自己的信息还能查当前城市或指定地点的天气预报。前端页面包括首页、登录页、注册页、结果展示页、用户列表页和文件上传页样式靠static里的CSS和JS支撑。后端逻辑写在views.py里用户和天气相关数据模型定义在models.py中调第三方天气API的代码单独放在api.py里。项目自带Django Admin后台管理入口数据库迁移文件齐全启动直接用manage.py runserver就行。目录结构清晰含templates模板文件夹、static静态资源、migrations数据库迁移记录还有标准的requirements.txt依赖清单和.gitignore适合刚学Django的人照着跑通、改功能或者当二次开发起点。本文还有配套的精品资源点击获取
