django-spicy-id

这是Django的AutoField的一个替代品，它为您提供类似Stripe风格的自我标识的字符串对象ID，如user_1234。

状态: 稳定。无保修，见LICENSE.txt。

目录

• 什么是“花哨”的ID？
• 为什么使用花哨的ID？
• 安装
  • 需求
  • 说明
• 用法
  • 字段类型
  • 必需参数
  • 可选参数
  • 注册URL
  • Django REST Framework
  • 字段属性
    • .validate_string(strval)
    • .re
    • .re_pattern
  • 实用方法
    • get_url_converter(model_class, field_name)
  • 错误
    • django.db.utils.ProgrammingError
    • django_spicy_id.MalformedSpicyIdError
• 技巧和窍门
  • 不要更改字段配置
• 变更日志

什么是“花哨”的ID？

这是一个虚构的名字（因为我没有想到更好的名字），用于表示一种数值主键类型，以字符串形式显示和处理，前面有一个固定值。

以下是几个示例。您可以使用这个库使您的Django行ID看起来像

• user_1234
• account-00000000deadbeef
• bloop:1a2k3841x

尽管你应该始终将这些值视为不透明的，并且永远不要在其他地方解码或解析字符串的内容（见错误），但你可以将每个spicy id看作是由以下部分组成的

<prefix> <separator> <encoded_value>

• 前缀：一个固定字符串值，对于此记录类型的所有ID，永远不变。
• 分隔符：一个可配置的分隔符，与前缀一样，永远不变；通常为_（默认）或-（另一种流行选择）。
• 编码值：ID的数字部分。此库支持使用16进制（十六进制）或62进制。

重要的是，底层数据库值仍然以数字类型存储和检索，就像AutoField、SmallAutoField或BigAutoField一样。

为什么使用花哨的ID？

简要来说：因为它们对人类来说更容易操作。

• 可读性：虽然行级主键通常被视为“匿名”（例如，“没有人需要关心的事情”），但事实上，这些值仍然在许多情况下出现：它们在URL中，被记录在日志文件中，在查询中显示，等等。在这些情况下，当标识符本身告诉你其类型时，理解“我在看什么”只是更快。
• 冲突和意外预防：当你的系统需要你传递像acct_1234和invoice_5432beef这样的带类型标识符时，某些类型的意外变得不可能。例如，HTTP DELETE /users/invoice_21会快速失败。
• 对未来进行保障：采用spicy IDs意味着你的系统和API是开发为接受一个基本不透明的字符串作为ID的。虽然它们的底层类型是数字，但在非常高级的情况下，你可能能够迁移到不同的类型或数据存储“在字符串ID创建的抽象后面”。

有关此模式的更多详细信息，请参阅Stripe的“Object IDs：Designing APIs for Humans”。

安装

需求

此包支持并针对以下最新补丁版本进行了测试

• Python 3.9, 3.10, 3.11, 3.12
• Django 3.2, 4.2
• MySQL 5.7, 8.0
• PostgreSQL 9.5, 10, 11, 12
• SQLite 3.9.0+

所有数据库后端都使用其驱动程序的最新版本进行了测试。SQLite还在GitHub Actions的最新macOS虚拟环境中进行了测试。

注意：建议使用Django 4.x，因为3.x中存在一个上游错误。有关详细信息，请参阅#6。

说明

pip install django_spicy_id

用法

给定以下示例模型

from django.db import models
from django_spicy_id import SpicyBigAutoField

class User(models.model):
    id = SpicyBigAutoField(primary_key=True, prefix='usr')

示例用法

>>> u = models.User.objects.create()
>>> u.id
'usr_1'
>>> u2 = models.User.objects.create(id=123456789)
>>> u2.id
'usr_8M0kX'
>>> found_user = models.User.objects.filter(id='usr_8M0kX').first()
>>> found_user == u2
True

字段类型

• SpicyBigAutoField：一个由BigAutoField（即64位整型）列支持的spicy id。
• SpicyAutoField：一个由AutoField（即32位整型）列支持的spicy id。
• SpicySmallAutoField：一个由SmallAutoField（即16位整型）列支持的spicy id。

必需参数

在声明时需要以下参数

• 前缀：在编码形式中使用的前缀。通常这是一个简短且描述性的字符串，如user或acct等。 注意：此库不确保你提供的字符串在项目中是唯一的。你应该确保这一点。

可选参数

除了所有可提供的参数外，上述每种字段类型还支持以下额外的可选参数

• 编码：使用哪种数字编码方案。可以是django_spicy_id.ENCODING_BASE_62（默认）、django_spicy_id.ENCODING_BASE_58或django_spicy_id.ENCODING_HEX之一。
• sep：分隔符字符。默认为_。可以是任何字符串。
• pad：ID的编码部分是否应该用零填充，以便所有值都具有相同的字符串长度。可以是False（默认）或True。
  • 无填充的示例：user_8M0kX
  • 带填充的示例：user_0000008M0kX
• randomize：如果设置为True，新记录的默认值将使用secrets.randbelow()随机生成。如果设置为False（默认值），则与正常AutoField一样工作，即默认值来自数据库的INSERT操作。
  • 当设置randomize时，如果同时设置了default，将会抛出错误，因为randomize本质上是一个特殊且内置的default函数。
  • 由于randomize安装了一个特殊的default函数，新的但未保存的模型实例将具有非None的object.id / object.pk值。您必须使用object._state.adding来确定实例是否为新的但未保存的对象。
  • 如果您使用此功能，请注意其风险
    • 生成的ID可能与现有行冲突，概率由生日问题确定（即列大小和现有数据集的大小）。
    • 如果两个进程为secrets.randbelow()生成相同的值（即如果系统熵相同或由于某些原因配置不当），也可能出现冲突。

注册URL

当安装必须匹配特定香辛料ID的路由时，您可以使用get_url_converter()辅助方法安装Django 自定义路径转换器。

使用此方法将确保只向视图呈现该字段的有效香辛料ID字符串。

示例

# models.py
class User(models.model):
    id = SpicyBigAutoField(primary_key=True, prefix='usr')

# urls.py
from . import models
from django.urls import path, register_converter
from django_spicy_id import get_url_converter

# Register the pattern for `User.id` as "spicy_user_id". You should do this
# once for each unique spicy ID field.
register_converter(get_url_converter(models.User, 'id'), 'spicy_user_id')

urlpatterns = [
    path('users/<spicy_user_id:id>', views.user_detail),
    ...
]

# views.py

def user_detail(request, id):
  user = models.User.objects.get(id=id)
  ...

Django REST Framework

Django REST Framework (DRF)基本上与django-spicy-id没有问题。但是，需要额外步骤，以便DRF将香辛料ID字段视为字符串，而不是整数，在序列化器中。

您可以使用包含的实用函数来修补DRF。可以安全地多次调用此方法。

from django_spicy_id import monkey_patch_drf

monkey_patch_drf()

字段属性

一旦构造，字段上就有以下属性

.validate_string(strval)

检查strval是否为字段的合法值，如果不合法则抛出django_spicy_id.errors.MalformedSpicyIdError。

.re

一个可以用来验证字符串的编译正则表达式。

.re_pattern

一个可以用来验证字符串的字符串正则表达式模式。与re中使用的模式不同，此模式不包括前导的^和尾随的$边界字符，这使得它在像Django URL模式这样的东西中使用起来更容易。

您可能不需要直接使用此属性，而是查看get_url_converter()。

实用方法

这些实用方法在顶层django_spicy_id模块上提供。

get_url_converter(model_class, field_name)

返回用于在model_class上的field_name的Django 自定义路径转换器。

有关示例用法，请参阅注册URL。

错误

django.db.utils.ProgrammingError

当尝试使用非法值访问或查询此字段时抛出。以下是一些这种情况的示例

• 提供具有错误前缀或分隔符的香辛料ID（例如，预期的id="invoice_1234"，但提供的是id="acct_1234"）。
• 提供一个包含非法字符的字符串（即编码部分不可解码）。
• 在启用填充时提供未填充的值。
• 在禁用填充时提供填充的值。

您可以将这些情况视为向其他任何字段类型提供错误类型对象的情况，例如SomeModel.objects.filter(id=object())。

您可以通过首先验证输入来避免这种情况。请参阅字段属性。

🚨 警告：无论字段配置如何，香辛料ID的字符串值必须始终被视为一个精确值。就像您永远不会修改UUID4的内容一样，香辛料ID字符串永远不应该被翻译、重新解释或由客户端更改。

django_spicy_id.MalformedSpicyIdError

ValueError的一个子类，由.validate_string(strval)在提供的字符串对于字段的配置无效时抛出。

技巧和窍门

不要更改字段配置

在开始使用字段之后更改prefix、sep、pad或encoding应被视为对外部调用者的破坏性更改。

虽然存储的行ID永远不会改变，但以前使用不同编码配置生成的任何辣条ID现在可能无效，或者（可能灾难性地）解析为不同的对象。

例如，user_10如果解析为hex与base62或base58，则自然地会指代不同的数字行ID。您应避免更改字段配置。

变更日志

请参阅CHANGELOG.md以获取变更摘要。