Django 框架在处理 Web 请求时，会将客户端发送的 HTTP 请求信息封装成一个 HttpRequest 对象。这个对象是视图函数接收到的第一个参数，通常命名为 request。理解 HttpRequest 对象的属性和方法对于编写高效、健壮的 Django 应用至关重要。它提供了访问请求元数据、GET/POST 参数、Cookies、Session、上传文件等所有与当前请求相关信息的接口。本文将详细介绍 HttpRequest 对象的常用属性和方法，并通过具体案例进行说明。
HttpRequest 对象概述
当一个 HTTP 请求到达 Django 应用时，经过 WSGI 服务器和一系列 Django 中间件的处理后，Django 会根据请求信息创建一个 HttpRequest 类的实例。这个实例包含了请求的所有细节，例如请求方法、请求头、请求体、URL 参数、表单数据等。随后，Django 的 URL 路由系统会根据请求的 URL 找到对应的视图函数，并将这个 HttpRequest 对象作为第一个参数传递给该视图函数。视图函数通过操作这个 request 对象来获取客户端信息，并据此生成相应的 HttpResponse 对象返回给客户端。
常用属性
HttpRequest 对象提供了丰富的属性来访问请求的不同部分。以下是一些最常用的属性及其用法。
path
该属性返回一个字符串，表示请求的路径部分，不包括域名和查询参数（GET 参数）。
案例: 如果客户端请求的 URL 是 http://example.com/articles/archive/?page=2，那么在视图函数中，request.path 的值将是 /articles/archive/。
# views.py
from django.http import HttpResponse
def article_archive(request):
path_info = request.path
# path_info 将是 '/articles/archive/'
return HttpResponse(f"Request path: {path_info}")method
该属性返回一个字符串，表示请求使用的 HTTP 方法，通常是大写的 'GET' 或 'POST'，但也可能是 'PUT'、'DELETE'、'HEAD'、'OPTIONS' 等。
案例: 视图函数可以根据请求方法执行不同的逻辑，例如处理表单提交时区分 GET 和 POST 请求。
# views.py
from django.shortcuts import render, redirect
def contact_form(request):
if request.method == 'POST':
# 处理表单提交逻辑
# ... form validation and processing ...
return redirect('success_page') # 假设提交成功后重定向
else: # 'GET' or other methods
# 显示空表单或带有初始数据的表单
return render(request, 'contact_form.html')GET
这是一个类字典对象 (QueryDict 实例)，包含了所有通过 HTTP GET 方法传递的参数（即 URL 查询字符串中的参数）。键和值都是字符串。同一个键可以有多个值。
案例: 处理 URL http://example.com/search/?q=django&category=web。
# views.py
from django.http import HttpResponse
def search_results(request):
query = request.GET.get('q', '') # 获取 'q' 参数，若不存在则返回空字符串
category = request.GET.get('category', 'all') # 获取 'category' 参数，默认值为 'all'
# 如果一个参数可能出现多次，如 ?tags=python&tags=django
tags = request.GET.getlist('tags') # 获取所有 'tags' 参数的值，返回一个列表
return HttpResponse(f"Search query: {query}, Category: {category}, Tags: {tags}")POST
这也是一个类字典对象 (QueryDict 实例)，包含了所有通过 HTTP POST 方法传递的参数，通常来自 HTML 表单提交。与 GET 类似，键和值都是字符串，同一个键也可以有多个值。只有当请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data 时，Django 才会填充 request.POST。
案例: 处理一个包含姓名和邮箱的 POST 表单。
# views.py
from django.http import HttpResponse
def subscribe(request):
if request.method == 'POST':
name = request.POST.get('name', 'Anonymous')
email = request.POST.get('email')
if email:
# 处理订阅逻辑
return HttpResponse(f"Subscription successful for {name} ({email})")
else:
return HttpResponse("Email is required.", status=400)
# 对于非 POST 请求，可以显示表单或返回错误
return HttpResponse("Please submit the form via POST.", status=405)COOKIES
这是一个标准的 Python 字典，包含了客户端发送的所有 Cookies。键和值都是字符串。
案例: 读取名为 user_preference 的 Cookie。
# views.py
from django.http import HttpResponse
def user_settings(request):
preference = request.COOKIES.get('user_preference', 'default_theme')
# 可以根据 preference 加载不同的设置
return HttpResponse(f"User preference from cookie: {preference}")FILES
这是一个类字典对象 (QueryDict 实例)，包含了所有通过 multipart/form-data 编码方式上传的文件。字典的每个值是一个 UploadedFile 对象。只有当请求方法为 POST 且包含 enctype="multipart/form-data" 的表单提交文件时，request.FILES 才会被填充。
案例: 处理用户上传头像的表单。
# forms.py
from django import forms
class ProfilePictureForm(forms.Form):
picture = forms.FileField()
# views.py
from django.shortcuts import render, redirect
# from .forms import ProfilePictureForm # 假设 form 在同目录的 forms.py
from django.core.files.storage import default_storage
def upload_profile_picture(request):
if request.method == 'POST':
form = ProfilePictureForm(request.POST, request.FILES)
if form.is_valid():
uploaded_file = request.FILES['picture']
# 处理文件保存逻辑
file_name = default_storage.save(uploaded_file.name, uploaded_file)
# 更新用户模型的头像字段等
return redirect('profile_page') # 上传成功后重定向
else:
form = ProfilePictureForm()
return render(request, 'upload_form.html', {'form': form})META
这是一个标准的 Python 字典，包含了所有可用的 HTTP 头部信息。可用的头部信息取决于客户端和服务器。常见的头部信息会被转换成 META 中的键，格式为 HTTP_ 加上大写的头部名称，并将连字符替换为下划线。例如，User-Agent 头部对应 request.META['HTTP_USER_AGENT']。此外，META 还包含一些由 WSGI 服务器设置的非 HTTP 头部信息，如 REMOTE_ADDR (客户端 IP 地址) 和 SERVER_NAME (服务器主机名)。
案例: 获取用户的 IP 地址和浏览器信息。
# views.py
from django.http import HttpResponse
def client_info(request):
ip_address = request.META.get('REMOTE_ADDR', 'Unknown IP')
user_agent = request.META.get('HTTP_USER_AGENT', 'Unknown Browser')
return HttpResponse(f"Client IP: {ip_address}<br>User Agent: {user_agent}")user
如果 Django 的认证系统中间件 (AuthenticationMiddleware) 被启用，这个属性将是一个 django.contrib.auth.models.User 或 AnonymousUser 的实例，代表当前与请求关联的用户。AnonymousUser 用于表示未登录的用户。
案例: 根据用户是否登录显示不同的内容。
# views.py
from django.http import HttpResponse
from django.contrib.auth.decorators import login_required
def user_profile(request):
if request.user.is_authenticated:
username = request.user.username
return HttpResponse(f"Welcome, {username}!")
else:
return HttpResponse("Please log in to view your profile.")
@login_required # 使用装饰器确保用户已登录
def protected_view(request):
# 只有登录用户能访问此视图
return HttpResponse(f"Hello, {request.user.username}! This is a protected area.")session
如果 Django 的会话中间件 (SessionMiddleware) 被启用，这个属性将是一个可读写的、类似字典的对象，代表当前的会话。可以使用它来存储和检索与特定浏览器会话相关的数据。
案例: 记录用户访问页面的次数。
# views.py
from django.http import HttpResponse
def visit_counter(request):
visits = request.session.get('visits', 0) + 1
request.session['visits'] = visits # 存储更新后的值
# 确保修改了 session 后 Django 会保存它
# request.session.modified = True # 通常 get/set 会自动标记为 modified
return HttpResponse(f"You have visited this page {visits} times in this session.")scheme
返回一个字符串，表示请求使用的协议，通常是 'http' 或 'https'。
案例: 判断请求是否通过安全连接发送。
# views.py
from django.http import HttpResponse
def check_security(request):
if request.scheme == 'https':
return HttpResponse("Request was made over a secure connection (HTTPS).")
else:
return HttpResponse("Request was made over an insecure connection (HTTP).")body
包含原始 HTTP 请求体内容的字节字符串。这对于处理非 HTML 表单数据（如 JSON、XML）或需要直接访问原始 POST 数据时非常有用。通常不建议直接访问 request.body 来处理表单数据，应该优先使用 request.POST。
案例: 处理一个发送 JSON 数据的 API 请求。
# views.py
import json
from django.http import JsonResponse, HttpResponseBadRequest
def api_endpoint(request):
if request.method == 'POST' and request.content_type == 'application/json':
try:
data = json.loads(request.body)
# 处理接收到的 JSON 数据 data
processed_data = {"status": "success", "received_data": data}
return JsonResponse(processed_data)
except json.JSONDecodeError:
return HttpResponseBadRequest("Invalid JSON format.")
return HttpResponseBadRequest("Invalid request method or content type.")content_type
返回请求体的 MIME 类型，从 Content-Type HTTP 头部获取。
案例: 见上一个 request.body 的案例，用于判断请求体是否为 JSON。
headers
一个不区分大小写的类字典对象，提供了对所有请求头的访问。与 request.META 不同，headers 直接映射 HTTP 头部名称（保留连字符），并且访问时不区分大小写。
案例: 获取 Authorization 头部信息。
# views.py
from django.http import HttpResponse
def get_auth_header(request):
auth_header = request.headers.get('Authorization')
if auth_header:
return HttpResponse(f"Authorization header found: {auth_header}")
else:
return HttpResponse("Authorization header not found.")常用方法
除了属性之外，HttpRequest 对象还提供了一些有用的方法。
get_full_path()
返回 path 属性的值加上一个问号和查询字符串（如果存在）。
案例: 获取完整的请求路径，包括 GET 参数。
# views.py
from django.http import HttpResponse
def show_full_path(request):
# 对于 URL http://example.com/articles/archive/?page=2&sort=date
full_path = request.get_full_path()
# full_path 将是 '/articles/archive/?page=2&sort=date'
return HttpResponse(f"Full request path: {full_path}")get_host()
返回请求的主机名（域名），根据 Host HTTP 头部信息确定。如果包含端口号，也会一并返回。
案例: 获取当前请求访问的域名。
# views.py
from django.http import HttpResponse
def show_host(request):
# 对于请求 http://example.com:8000/some/path/
host = request.get_host()
# host 将是 'example.com:8000'
return HttpResponse(f"Requested host: {host}")is_secure()
返回一个布尔值，True 表示请求是通过 HTTPS 发起的，否则返回 False。这通常是通过检查 request.scheme 属性是否为 'https' 来实现的，但它也可能考虑由代理服务器设置的 X-Forwarded-Proto 头部（如果配置了 SECURE_PROXY_SSL_HEADER 设置）。
案例: 检查请求是否安全，并可能据此采取不同操作。
# views.py
from django.http import HttpResponse
def secure_check_view(request):
if request.is_secure():
# 处理安全请求的逻辑
return HttpResponse("This request is secure (HTTPS).")
else:
# 处理非安全请求的逻辑，或建议使用 HTTPS
return HttpResponse("This request is not secure (HTTP). Consider using HTTPS.")build_absolute_uri(location=None)
返回指定 location 的绝对 URI (包含协议和域名)。如果 location 未提供或为 None，则默认使用 request.get_full_path() 作为路径。这对于生成在邮件、API 响应或重定向中使用的完整 URL 非常有用。
案例: 生成一个指向当前页面的完整 URL。
# views.py
from django.http import HttpResponse
def show_absolute_uri(request):
# 生成当前请求的完整绝对 URL
current_absolute_uri = request.build_absolute_uri()
# 生成指向 '/profile/' 页面的完整绝对 URL
profile_absolute_uri = request.build_absolute_uri('/profile/')
return HttpResponse(f"Current Absolute URI: {current_absolute_uri}<br>"
f"Profile Absolute URI: {profile_absolute_uri}")假设请求是 http://example.com/some/path/?query=abc，那么： current_absolute_uri 会是 http://example.com/some/path/?query=abcprofile_absolute_uri 会是 http://example.com/profile/
理解 QueryDict
request.GET 和 request.POST 返回的对象类型是 django.http.QueryDict。它继承自 Python 的字典，但特别设计用来处理同一个键可能对应多个值的情况，这在 HTML 表单（例如多选框）和 URL 查询字符串中很常见。
QueryDict.get(key, default=None): 只返回指定键的最后一个值。如果键不存在，返回default。QueryDict.getlist(key, default=None): 返回一个包含指定键所有值的 Python 列表。如果键不存在，返回default（默认为一个空列表[]，除非显式提供了default值）。QueryDict.__getitem__(key)(即qd[key]): 只返回指定键的最后一个值。如果键不存在或有多个值，可能会引发KeyError或行为取决于具体子类实现，推荐使用get()或getlist()。
案例: 处理一个有多选框的表单。
HTML 表单可能包含: <input type="checkbox" name="options" value="a"><input type="checkbox" name="options" value="b" checked><input type="checkbox" name="options" value="c" checked>
# views.py
from django.http import HttpResponse
def handle_multivalue(request):
if request.method == 'POST':
# 使用 get 只会得到最后一个选中的值 ('c')
last_option = request.POST.get('options')
# 使用 getlist 获取所有选中的值 (['b', 'c'])
all_options = request.POST.getlist('options')
return HttpResponse(f"Last option selected: {last_option}<br>"
f"All options selected: {all_options}")
# 显示表单的逻辑...
return HttpResponse("Submit the form via POST.")HttpRequest 与中间件
HttpRequest 对象在到达视图之前会经过一系列 Django 中间件的处理。中间件可以修改 request 对象，例如添加属性（如 request.user 和 request.session 就是由相应的中间件添加的）或执行其他预处理任务。了解中间件如何影响 HttpRequest 对象有助于调试和理解请求处理流程。
上图展示了请求对象在中间件和视图之间传递的基本流程。
小结
HttpRequest 对象是 Django Web 开发的核心组件之一，它封装了客户端请求的所有信息。通过其丰富的属性（如 path, method, GET, POST, COOKIES, FILES, META, user, session, body, headers）和方法（如 get_full_path, get_host, is_secure, build_absolute_uri），开发者可以方便地访问和处理请求数据。理解 QueryDict 的特性对于正确处理表单和 URL 参数至关重要。同时，认识到中间件对 HttpRequest 对象的潜在修改有助于把握整个请求生命周期。熟练掌握 HttpRequest 对象是编写高效、功能完善的 Django 应用的基础。