Django reCAPTCHA 使用与技术文档

1. 安装指南

首先，您需要在Django reCAPTCHA的页面上注册reCAPTCHA。注册完成后，您将获得一对公钥和私钥，这对于reCAPTCHA的正常工作至关重要。

接下来，通过pip命令安装Django reCAPTCHA：

pip install django-recaptcha

在您的Django项目的settings.py文件中，添加'django_recaptcha'到INSTALLED_APPS列表中：

INSTALLED_APPS = [
    # ... 其他应用 ...
    'django_recaptcha',
    # ... 其他应用 ...
]

然后，在settings.py中配置reCAPTCHA的公钥和私钥：

RECAPTCHA_PUBLIC_KEY = '您的reCAPTCHA公钥'
RECAPTCHA_PRIVATE_KEY = '您的reCAPTCHA私钥'

如果需要使用代理，可以设置RECAPTCHA_PROXY：

RECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'}

如果www.google.com无法访问，可以将RECAPTCHA_DOMAIN设置为www.recaptcha.net：

RECAPTCHA_DOMAIN = 'www.recaptcha.net'

2. 项目的使用说明

要在表单中添加reCAPTCHA，可以使用ReCaptchaField字段类。默认情况下，它将渲染一个reCAPTCHA V2 Checkbox。

例如：

from django import forms
from django_recaptcha.fields import ReCaptchaField

class FormWithCaptcha(forms.Form):
    captcha = ReCaptchaField()

您还可以在运行时指定密钥，通过向构造函数传递private_key或public_key参数：

captcha = ReCaptchaField(
    public_key='您的公钥',
    private_key='您的私钥'
)

3. 项目API使用文档

ReCaptchaField支持以下几种小部件：

• ReCaptchaV2Checkbox：用于Google reCAPTCHA V2 Checkbox。
• ReCaptchaV2Invisible：用于Google reCAPTCHA V2 Invisible。
• ReCaptchaV3：用于Google reCAPTCHA V3。

要使用非默认的reCAPTCHA V2 Checkbox小部件，只需替换ReCaptchaField的小部件。例如：

from django import forms
from django_recaptcha.fields import ReCaptchaField
from django_recaptcha.widgets import ReCaptchaV2Invisible

class FormWithCaptcha(forms.Form):
    captcha = ReCaptchaField(widget=ReCaptchaV2Invisible)

reCAPTCHA V3还返回一个分数值，用于确定页面交互是机器人的可能性。可以通过设置RECAPTCHA_REQUIRED_SCORE来设定项目范围的分数限制：

RECAPTCHA_REQUIRED_SCORE = 0.85

也可以在运行时为每个字段指定分数：

captcha = fields.ReCaptchaField(
    widget=ReCaptchaV3(required_score=0.85)
)

如果分数不符合要求，字段验证将失败，并记录错误信息。

reCAPTCHA V3 API还支持传递一个动作值，用于将reCAPTCHA验证与您网站上的特定表单关联起来，以便进行风险分析。设置动作值时，可以使用以下方式：

captcha = fields.ReCaptchaField(
    widget=widgets.ReCaptchaV3(
        action='signup'
    )
)

设置动作是可选的，如果不指定动作，则不会向reCAPTCHA V3 API传递任何动作。

4. 项目安装方式

请遵循上述安装指南中的步骤进行安装。确保已经注册了reCAPTCHA并获取了公钥和私钥，然后通过pip安装Django reCAPTCHA，并在Django项目的配置文件中进行了相应设置。