Django2.0手册:Conditional View Processing

The condition decorator¶

Sometimes (in fact, quite often) you can create functions to rapidly compute the ETag
value or the last-modified time for a resource, without needing to do all
the computations needed to construct the full view. Django can then use these
functions to provide an “early bailout” option for the view processing.
Telling the client that the content has not been modified since the last
request, perhaps.

These two functions are passed as parameters to the
django.views.decorators.http.condition decorator. This decorator uses
the two functions (you only need to supply one, if you can’t compute both
quantities easily and quickly) to work out if the headers in the HTTP request
match those on the resource. If they don’t match, a new copy of the resource
must be computed and your normal view is called.

The condition decorator’s signature looks like this:

condition(etag_func=None, last_modified_func=None)

The two functions, to compute the ETag and the last modified time, will be
passed the incoming request object and the same parameters, in the same
order, as the view function they are helping to wrap. The function passed
last_modified_func should return a standard datetime value specifying the
last time the resource was modified, or None if the resource doesn’t
exist. The function passed to the etag decorator should return a string
representing the ETag for the resource, or None if it doesn’t exist.

The decorator sets the ETag and Last-Modified headers on the response
if they are not already set by the view and if the request’s method is safe
(GET or HEAD).

Using this feature usefully is probably best explained with an example.
Suppose you have this pair of models, representing a simple blog system:

import datetime
from django.db import models

class Blog(models.Model):
    ...

class Entry(models.Model):
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)
    published = models.DateTimeField(default=datetime.datetime.now)
    ...

If the front page, displaying the latest blog entries, only changes when you
add a new blog entry, you can compute the last modified time very quickly. You
need the latest published date for every entry associated with that blog.
One way to do this would be:

def latest_entry(request, blog_id):
    return Entry.objects.filter(blog=blog_id).latest("published").published

You can then use this function to provide early detection of an unchanged page
for your front page view:

from django.views.decorators.http import condition

@condition(last_modified_func=latest_entry)
def front_page(request, blog_id):
    ...

Shortcuts for only computing one value¶

As a general rule, if you can provide functions to compute both the ETag and
the last modified time, you should do so. You don’t know which headers any
given HTTP client will send you, so be prepared to handle both. However,
sometimes only one value is easy to compute and Django provides decorators
that handle only ETag or only last-modified computations.

The django.views.decorators.http.etag and
django.views.decorators.http.last_modified decorators are passed the same
type of functions as the condition decorator. Their signatures are:

etag(etag_func)
last_modified(last_modified_func)

We could write the earlier example, which only uses a last-modified function,
using one of these decorators:

@last_modified(latest_entry)
def front_page(request, blog_id):
    ...

…or:

def front_page(request, blog_id):
    ...
front_page = last_modified(latest_entry)(front_page)

# Bad code. Don't do this!
@etag(etag_func)
@last_modified(last_modified_func)
def my_view(request):
    # ...

# End of bad code.

Using the decorators with other HTTP methods¶

The condition decorator is useful for more than only GET and
HEAD requests (HEAD requests are the same as GET in this
situation). It can also be used to provide checking for POST,
PUT and DELETE requests. In these situations, the idea isn’t to return
a “not modified” response, but to tell the client that the resource they are
trying to change has been altered in the meantime.

For example, consider the following exchange between the client and server:

1. 用户请求“/foo/“。
2. Server responds with some content with an ETag of "abcd1234".
3. Client sends an HTTP PUT request to /foo/ to update the
   resource. It also sends an If-Match: "abcd1234" header to specify
   the version it is trying to update.
4. Server checks to see if the resource has changed, by computing the ETag
   the same way it does for a GET request (using the same function).
   If the resource has changed, it will return a 412 status code,
   meaning “precondition failed”.
5. Client sends a GET request to /foo/, after receiving a 412
   response, to retrieve an updated version of the content before updating
   it.

The important thing this example shows is that the same functions can be used
to compute the ETag and last modification values in all situations. In fact,
you should use the same functions, so that the same values are returned
every time.

Comparison with middleware conditional processing¶

Django provides simple and straightforward conditional GET handling via
django.middleware.http.ConditionalGetMiddleware. While being easy to
use and suitable for many situations, the middleware has limitations for
advanced usage:

• It’s applied globally to all views in your project.
• It doesn’t save you from generating the response, which may be expensive.
• It’s only appropriate for HTTP GET requests.

You should choose the most appropriate tool for your particular problem here.
If you have a way to compute ETags and modification times quickly and if some
view takes a while to generate the content, you should consider using the
condition decorator described in this document. If everything already runs
fairly quickly, stick to using the middleware and the amount of network
traffic sent back to the clients will still be reduced if the view hasn’t
changed.