hertz_django/hertz_studio_django_utils

Hertz Studio Django Utils 模块

概述

Hertz Studio Django Utils 是一个功能丰富的工具类模块，为 Hertz Server Django 项目提供核心的工具函数、响应格式、验证器和加密服务。该模块采用模块化设计，便于维护和扩展。

功能特性

• 🔐 加密工具: 提供多种加密算法和密码哈希功能
• 📧 邮件服务: 统一的邮件发送接口和验证码邮件模板
• 📋 响应格式: 标准化的API响应格式和错误处理
• ✅ 数据验证: 邮箱、密码、手机号等格式验证
• 🧩 模块化设计: 各功能模块独立，便于按需使用

模块结构

hertz_studio_django_utils/
├── __init__.py              # 模块初始化
├── crypto/                  # 加密工具
│   ├── __init__.py
│   ├── encryption_utils.py # 通用加密工具
│   └── password_hashers.py  # 密码哈希器
├── email/                   # 邮件服务
│   ├── __init__.py
│   └── email_service.py    # 邮件发送服务
├── responses/               # 响应格式
│   ├── __init__.py
│   └── HertzResponse.py    # 统一响应类
└── validators/              # 验证器
    ├── __init__.py
    ├── email_validator.py  # 邮箱验证器
    ├── password_validator.py # 密码验证器
    └── phone_validator.py  # 手机号验证器

核心类说明

1. EncryptionUtils 加密工具类

提供多种加密算法和工具函数：

from hertz_studio_django_utils.crypto import EncryptionUtils

# MD5哈希
hash_value = EncryptionUtils.md5_hash("password", "salt")

# SHA256哈希
hash_value = EncryptionUtils.sha256_hash("password", "salt")

# 数据加密解密
encrypted = EncryptionUtils.encrypt_data("敏感数据", "password")
decrypted = EncryptionUtils.decrypt_data(encrypted, "password")

# 生成随机盐值
salt = EncryptionUtils.generate_salt(32)

2. MD5PasswordHasher MD5密码哈希器

兼容旧系统的MD5密码加密：

from hertz_studio_django_utils.crypto import MD5PasswordHasher

hasher = MD5PasswordHasher()
encoded_password = hasher.encode("password", "salt")
is_valid = hasher.verify("password", encoded_password)

3. EmailService 邮件服务类

提供邮件发送功能：

from hertz_studio_django_utils.email import EmailService

# 发送普通邮件
success = EmailService.send_email(
    recipient_email="user@example.com",
    subject="邮件主题",
    html_content="<h1>HTML内容</h1>",
    text_content="纯文本内容"
)

# 发送验证码邮件
success = EmailService.send_verification_code(
    recipient_email="user@example.com",
    recipient_name="用户名",
    verification_code="123456",
    code_type="register"
)

4. HertzResponse 统一响应类

标准化的API响应格式：

from hertz_studio_django_utils.responses import HertzResponse

# 成功响应
return HertzResponse.success(data={"user": user_data}, message="操作成功")

# 失败响应
return HertzResponse.fail(message="操作失败", data={"error": "详情"})

# 错误响应
return HertzResponse.error(message="系统错误", error=str(e))

# 验证错误
return HertzResponse.validation_error(message="参数错误", errors=serializer.errors)

# 自定义响应
return HertzResponse.custom(
    success=True, 
    message="自定义消息", 
    data={"custom": "data"},
    code=200
)

5. 验证器类

提供数据格式验证功能：

from hertz_studio_django_utils.validators import (
    EmailValidator, PasswordValidator, PhoneValidator
)

# 邮箱验证
is_valid, message = EmailValidator.validate_email("test@example.com")
normalized_email = EmailValidator.normalize_email(" Test@Example.COM ")

# 密码强度验证
is_valid, errors = PasswordValidator.validate_password_strength("Password123!")
score = PasswordValidator.calculate_password_score("Password123!")
level = PasswordValidator.get_password_strength_level("Password123!")

# 手机号验证
is_valid = PhoneValidator.is_valid_china_mobile("13800138000")
is_valid, message = PhoneValidator.validate_china_mobile("13800138000")
carrier = PhoneValidator.get_mobile_carrier("13800138000")

安装和配置

1. 依赖安装

确保已安装以下依赖：

pip install Django>=5.2.6
pip install cryptography>=41.0.0

2. 配置邮件服务

在 settings.py 中配置邮件服务：

# 邮件配置
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.example.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@example.com'
EMAIL_HOST_PASSWORD = 'your-password'
DEFAULT_FROM_EMAIL = 'noreply@example.com'

3. 配置密码哈希器

在 settings.py 中配置密码哈希器：

PASSWORD_HASHERS = [
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
    'django.contrib.auth.hashers.Argon2PasswordHasher',
    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
    'hertz_studio_django_utils.crypto.password_hashers.MD5PasswordHasher',  # MD5兼容
]

快速开始

1. 导入模块

# 导入整个工具模块
from hertz_studio_django_utils import (
    EncryptionUtils,
    MD5PasswordHasher,
    EmailService,
    HertzResponse,
    EmailValidator,
    PasswordValidator,
    PhoneValidator
)

# 或按需导入特定功能
from hertz_studio_django_utils.responses import HertzResponse
from hertz_studio_django_utils.email import EmailService

2. 使用示例

# 在Django视图中使用统一响应
from rest_framework.decorators import api_view
from hertz_studio_django_utils.responses import HertzResponse

@api_view(['GET'])
def user_profile(request):
    try:
        user_data = {"username": "testuser", "email": "test@example.com"}
        return HertzResponse.success(data=user_data, message="获取用户信息成功")
    except Exception as e:
        return HertzResponse.error(message="获取用户信息失败", error=str(e))

# 发送验证码邮件
from hertz_studio_django_utils.email import EmailService

success = EmailService.send_verification_code(
    recipient_email="user@example.com",
    recipient_name="张三",
    verification_code="654321",
    code_type="register"
)

if success:
    print("验证码邮件发送成功")
else:
    print("验证码邮件发送失败")

API接口

加密工具 API

方法	描述	参数	返回值
md5_hash(data, salt)	MD5哈希加密	data: str, salt: str	str
sha256_hash(data, salt)	SHA256哈希加密	data: str, salt: str	str
encrypt_data(data, password)	加密数据	data: str, password: str	Optional[str]
decrypt_data(encrypted_data, password)	解密数据	encrypted_data: str, password: str	Optional[str]
generate_salt(length)	生成随机盐值	length: int	str

邮件服务 API

方法	描述	参数	返回值
send_email()	发送邮件	recipient_email, subject, html_content, text_content, from_email	bool
send_verification_code()	发送验证码邮件	recipient_email, recipient_name, verification_code, code_type	bool

响应格式 API

方法	描述	参数	返回值
success()	成功响应	data, message, code	JsonResponse
fail()	失败响应	message, data, code	JsonResponse
error()	错误响应	message, error, code	JsonResponse
unauthorized()	未授权响应	message, code	JsonResponse
validation_error()	验证错误响应	message, errors, code	JsonResponse
custom()	自定义响应	success, message, data, code, **kwargs	JsonResponse

验证器 API

类	方法	描述
EmailValidator	is_valid_email()	验证邮箱格式
	validate_email()	验证邮箱并返回详细信息
	normalize_email()	标准化邮箱地址
PasswordValidator	validate_password_strength()	验证密码强度
	calculate_password_score()	计算密码强度分数
	get_password_strength_level()	获取密码强度等级
PhoneValidator	is_valid_china_mobile()	验证中国大陆手机号
	validate_china_mobile()	验证手机号并返回详细信息
	normalize_phone()	标准化手机号

配置参数

邮件服务配置

参数	默认值	描述
EMAIL_HOST	-	SMTP服务器地址
EMAIL_PORT	587	SMTP端口
EMAIL_USE_TLS	True	使用TLS加密
EMAIL_HOST_USER	-	SMTP用户名
EMAIL_HOST_PASSWORD	-	SMTP密码
DEFAULT_FROM_EMAIL	-	默认发件人邮箱

密码验证配置

参数	默认值	描述
min_length	8	密码最小长度
max_length	128	密码最大长度

高级用法

自定义邮件模板

from hertz_studio_django_utils.email import EmailService

# 自定义邮件内容
custom_html = """
<html>
<body>
    <h1>自定义邮件</h1>
    <p>您好 {name}，这是一封自定义邮件。</p>
</body>
</html>
""".format(name="张三")

success = EmailService.send_email(
    recipient_email="user@example.com",
    subject="自定义邮件",
    html_content=custom_html
)

扩展响应格式

from hertz_studio_django_utils.responses import HertzResponse

# 扩展自定义响应
class CustomResponse(HertzResponse):
    @staticmethod
    def paginated(data, total, page, page_size, message="查询成功"):
        """分页响应"""
        pagination = {
            "total": total,
            "page": page,
            "page_size": page_size,
            "total_pages": (total + page_size - 1) // page_size
        }
        return HertzResponse.success(
            data={"items": data, "pagination": pagination},
            message=message
        )

# 使用扩展响应
return CustomResponse.paginated(
    data=users, 
    total=100, 
    page=1, 
    page_size=20,
    message="用户列表查询成功"
)

测试

单元测试示例

from django.test import TestCase
from hertz_studio_django_utils.validators import EmailValidator

class EmailValidatorTest(TestCase):
    def test_valid_email(self):
        """测试有效邮箱地址"""
        is_valid, message = EmailValidator.validate_email("test@example.com")
        self.assertTrue(is_valid)
        self.assertEqual(message, "邮箱地址格式正确")
    
    def test_invalid_email(self):
        """测试无效邮箱地址"""
        is_valid, message = EmailValidator.validate_email("invalid-email")
        self.assertFalse(is_valid)
        self.assertEqual(message, "邮箱地址格式不正确")

运行测试

python manage.py test hertz_studio_django_utils.tests

安全考虑

1. 密码安全: 使用强密码哈希算法，避免明文存储密码
2. 加密安全: 使用安全的加密算法和随机盐值
3. 输入验证: 对所有输入数据进行严格验证
4. 错误处理: 避免泄露敏感错误信息
5. 邮件安全: 使用TLS加密邮件传输

常见问题

Q: 邮件发送失败怎么办？

A: 检查邮件配置是否正确，包括SMTP服务器、端口、用户名和密码。

Q: MD5密码哈希是否安全？

A: MD5被认为是不安全的哈希算法，仅用于兼容旧系统。新系统应使用更安全的算法如bcrypt或Argon2。

Q: 如何自定义响应格式？

A: 可以继承 HertzResponse 类并添加自定义方法。

Q: 验证器是否支持国际手机号？

A: 目前主要支持中国大陆手机号验证，国际手机号验证功能有限。

更新日志

v1.0.0 (2024-01-01)

• 初始版本发布
• 包含加密工具、邮件服务、响应格式、验证器等核心功能

🔗 相关链接

• 🏠 返回主项目 - Hertz Server Django 主项目
• 🔐 认证授权模块 - 用户管理和权限控制
• 🖼️ 验证码模块 - 图片和邮箱验证码功能
• 📋 代码风格指南 - 开发规范和最佳实践
• Django 官方文档
• Django REST Framework 文档

贡献指南

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

支持

如有问题或建议，请提交 Issue 或联系开发团队。