Django-common-helpers 技术文档

概述

Django-common-helpers 是一个为 Django 项目提供常用功能的扩展库。它包含了一系列实用的工具和功能，帮助开发者更高效地构建和维护 Django 应用。以下是该库的主要功能：

• 中间件：确保应用在带或不带 www 的域名下正常运行。
• SessionManagerBase 基类：帮助保持会话相关代码的面向对象和整洁。
• EmailBackend：允许用户通过电子邮件进行身份验证。
• 自定义数据库字段：如 UniqueHashField 和 RandomHashField。
• 辅助函数：提供了一系列有用的工具函数。
• render_form_field 模板标签：简化表单字段的渲染。
• 响应类：如 JsonResponse 和 XMLResponse，用于返回 JSON 或 XML 格式的响应。

安装指南

1. 安装

首先，使用 pip 安装 django-common-helpers，或者将代码复制到项目的目录中：

pip install django-common-helpers

2. 配置

在 Django 项目的 settings.py 文件中进行以下配置：

• 将 django_common 添加到 INSTALLED_APPS 中：

INSTALLED_APPS = [
    # ...
    "django_common",
]

• 添加以下设置项，并根据实际情况填写值：

IS_DEV = True  # 是否为开发环境
IS_PROD = False  # 是否为生产环境
DOMAIN_NAME = "example.com"  # 域名
WWW_ROOT = "https://www.example.com/"  # 网站根 URL

• 将 common_settings 添加到 TEMPLATE_CONTEXT_PROCESSORS 中：

TEMPLATE_CONTEXT_PROCESSORS = [
    # ...
    'django_common.context_processors.common_settings',
]

• 将 EmailBackend 添加到 AUTHENTICATION_BACKENDS 中：

AUTHENTICATION_BACKENDS = (
    'django_common.auth_backends.EmailBackend',
    'django.contrib.auth.backends.ModelBackend'
)

• 如果需要，将 WWWRedirectMiddleware 添加到中间件列表中：

MIDDLEWARE_CLASSES = [
    # ...
    "WWWRedirectMiddleware",
]

使用说明

1. 脚手架功能

脚手架功能可以帮助快速生成模型、视图、表单、模板、管理界面和基本测试。

安装脚手架

下载 scaffold 分支的代码，并将其添加到 INSTALLED_APPS 中。在 settings.py 中设置 SCAFFOLD_APPS_DIR，默认为主应用目录。

SCAFFOLD_APPS_DIR = 'apps/'

运行脚手架

使用以下命令生成应用和模型：

python manage.py scaffold APPNAME --model MODELNAME [fields]

• APPNAME：应用名称。如果应用不存在，将会被创建。
• MODELNAME：模型名称。只能生成一个模型。
• [fields]：模型字段列表。

字段类型

支持的字段类型包括：

• char：CharField
• text：TextField
• int：IntegerField
• decimal：DecimalField
• datetime：DateTimeField
• foreign：ForeignKey

示例

生成一个简单的 forum 应用，包含 Forum、Topic 和 Post 模型：

python manage.py scaffold forum --model Forum char:name
python manage.py scaffold forum --model Topic foreign:created_by:User char:title foreign:forum:Forum
python manage.py scaffold forum --model Post char:title text:body foreign:created_by:User foreign:topic:Topic

2. 生成 SECRET_KEY

使用以下命令生成新的 SECRET_KEY：

python manage.py generate_secret_key

可选参数：

• --length：密钥长度，默认为 50。
• --alphabet：生成密钥的字符集，默认为 ASCII 字母和标点符号。

API 使用文档

1. SessionManagerBase

SessionManagerBase 是一个基类，用于管理会话相关的代码。通过继承该类，可以保持会话代码的整洁和面向对象。

2. EmailBackend

EmailBackend 允许用户通过电子邮件进行身份验证。在 AUTHENTICATION_BACKENDS 中添加该后端后，用户可以使用电子邮件登录。

3. render_form_field 模板标签

render_form_field 是一个模板标签，用于简化表单字段的渲染。在模板中使用该标签可以避免重复代码。

4. JsonResponse 和 XMLResponse

JsonResponse 和 XMLResponse 是用于返回 JSON 或 XML 格式响应的类。在视图中使用这些类可以方便地返回结构化数据。

项目安装方式

1. 使用 pip 安装

pip install django-common-helpers

2. 手动安装

将 django-common-helpers 的代码复制到项目的目录中，并在 settings.py 中进行相应配置。

总结

Django-common-helpers 提供了一系列实用的工具和功能，帮助开发者更高效地构建和维护 Django 应用。通过本文档，您可以快速了解如何安装、配置和使用该库，以及如何利用其提供的功能来简化开发流程。