后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载地址是电商系统中最常见却也最容易做错的数据实体——它既要承载用户通讯录address book又要成为订单快照的一部分下单后不可篡改还要支持国家/地区差异化校验。Django Oscar 将这一复杂性收敛在一个只提供模型、不提供任何视图的 address 应用中并通过 5 个抽象模型实现了用户地址、配送地址、账单地址、合作方地址的复用与解耦。读完本文你将掌握 Oscar 地址模型的完整字段设计、国家邮政编码校验规则、地址去重哈希机制、默认地址唯一性约束以及OSCAR_REQUIRED_ADDRESS_FIELDS等关键配置的实战用法。应用定位只做模型的“基础服务”在 Oscar 的 16 个核心应用中见 ref/apps/index.rstaddress 是一个特殊的“基础服务”型应用。官方文档address.rst明确写道The address app provides core address models - it doesnt provide any views or other functionality.也就是说它不提供视图、表单、URL 路由等任何对外交互能力只负责定义可复用的地址数据模型。这一点从应用配置中可以得到印证——apps.py 中的AddressConfig只是声明了label address与name oscar.apps.address没有任何get_urls()或视图注册逻辑。它存在的意义是让其他应用order、partner、checkout、customer 等共享同一套地址字段定义与行为逻辑避免重复造轮子。抽象模型体系5 个抽象模型与 2 个具象落地文档指出5 个抽象模型中只有 2 个在oscar.apps.address.models中拥有非抽象版本其余的被其他应用继承落地。打开 abstract_models.py 可以看到完整的继承树抽象模型落地的具体模型归属应用用途AbstractAddress仅作基类address所有地址的超类被其余抽象模型继承AbstractCountryCountryaddressISO 3166 国家表AbstractUserAddressUserAddressaddress用户的“通讯录”地址AbstractShippingAddressShippingAddressorder订单配送地址快照AbstractBillingAddressBillingAddressorder订单账单地址快照AbstractPartnerAddressPartnerAddresspartner合作方供应商/物流商地址具体落地位置分别是address/models.pyUserAddress与Countryorder/models.pyShippingAddress与BillingAddresspartner/models.pyPartnerAddress。落地方式统一采用 Oscar 的“抽象模型 动态注册”模式所有具体模型类都是抽象类的空子类如class UserAddress(AbstractUserAddress): pass并且全部通过is_model_registered(...)守卫包裹允许开发者 fork 后用自己的模型覆盖这正是 Oscar 可定制化customisation架构的基石。为什么配送/账单地址要独立成模型AbstractUserAddress的 docstring 给出了关键设计理由abstract_models.pyWe use a separate model for shipping and billing (even though there will be some data duplication) because we dont want shipping/billing addresses changed or deleted once an order has been placed.用户地址是可变的用户可以增删改自己的通讯录而订单地址是不可变快照——订单一旦生成其配送/账单地址必须保持原样即使顾客事后修改了通讯录也不能影响已下的订单。因此 Oscar 刻意让ShippingAddress/BillingAddress独立于UserAddress允许用户随意编辑通讯录而不会污染历史订单。AbstractShippingAddress的 docstring 还解释了另一个历史遗留问题abstract_models.py为什么配送地址逻辑上属于 order 应用类却定义在 address 应用中原因是get_model/get_class的动态加载机制在 Django 1.7 之前注册 receiver 时会放大循环导入问题所以把抽象类放在 address、具体模型注册到 orderapp_label order既避免了循环导入又保持了模型归属清晰。AbstractAddress一切地址的超类AbstractAddress是地址体系的核心定义了所有地址共享的字段、校验与辅助方法。核心字段设计code NullCharField(_(Code), max_length255, blankTrue, nullTrue, uniqueTrue) title models.CharField(_(Title), max_length64, choicesTITLE_CHOICES, blankTrue) first_name models.CharField(_(First name), max_length255, blankTrue) last_name models.CharField(_(Last name), max_length255, blankTrue) line1 models.CharField(_(First line of address), max_length255) line2 models.CharField(_(Second line of address), max_length255, blankTrue) line3 models.CharField(_(Third line of address), max_length255, blankTrue) line4 models.CharField(_(City), max_length255, blankTrue) state models.CharField(_(State/County), max_length255, blankTrue) postcode UppercaseCharField(_(Post/Zip-code), max_length64, blankTrue) country models.ForeignKey(address.Country, on_deletemodels.CASCADE)几个值得注意的设计细节code字段可选的唯一地址代码uniqueTrue、允许为空用于外部系统同步或业务标识NullCharField是 Oscar 在 models/fields 中实现的“空串即 NULL”字段避免唯一约束被多个空串破坏。多行地址 line4即城市line1是唯一必填行未设blankTrueline2/line3为可选附加行line4实际承载“城市”语义并提供了city别名属性return self.line4。这种设计允许地址行数随国家习惯伸缩——注释里说明“地址行往往很长隐藏多余行比增加行更简单”。title称谓通过TITLE_CHOICES限定为Mr / Miss / Mrs / Ms / Dr五档title字段本身允许为空blankTrue。postcode使用UppercaseCharField保证邮政编码在数据库层面统一大写。country必填外键关联到address.Country级联删除。国家级邮政编码校验POSTCODES_REGEX这是 Oscar 地址模型最“重”的能力之一。AbstractAddress内置了一张覆盖约 120 个国家和地区的邮政编码正则表POSTCODES_REGEXabstract_models.py例如GB: r^[A-Z][A-Z0-9]{1,3}[0-9][A-Z]{2}$, # 英国 US: r^[0-9]{5}(-[0-9]{4}|-[0-9]{6})?$, # 美国含 ZIP4 JP: r^[0-9]{3}-?[0-9]{4}$, # 日本 CN: r^[0-9]{6}$, # 中国 DE: r^[0-9]{5}$, # 德国表注释明确说明未列入的国家视为不使用邮政编码。该校验在ensure_postcode_is_valid_for_country()中执行abstract_models.py逻辑分两路该填没填当postcode为空、但配置要求必填POSTCODE_REQUIRED为真且已选国家时抛出ValidationError(Addresses in %(country)s require a valid postcode)。填了不合法校验时会先把邮政编码统一转为大写并去掉空格self.postcode.upper().replace( , )再与对应国家的正则匹配不匹配则报错The postcode %(postcode)s is not valid for %(country)s并绑定到postcode字段上。POSTCODE_REQUIRED由类属性动态计算POSTCODE_REQUIRED postcode in settings.OSCAR_REQUIRED_ADDRESS_FIELDS即“是否强制要求邮编”完全取决于配置项OSCAR_REQUIRED_ADDRESS_FIELDS中是否包含postcode见下文配置小节。clean() 与 save() 的钩子def clean(self): # Strip all whitespace for field in [...]: if self.__dict__[field]: self.__dict__[field] self.__dict__[field].strip() self.ensure_postcode_is_valid_for_country() def save(self, *args, **kwargs): self._update_search_text() super().save(*args, **kwargs)clean()会在表单校验时自动被 Django 调用先把first_name、last_name、line1~line4、state、postcode的前后空白全部剥离再执行邮编校验。save()在每次保存前都会重建search_text字段_update_search_text()保证搜索索引数据始终与实体字段同步。search_text穷人版 Solr 全文检索AbstractAddress里有一个专门的搜索字段abstract_models.pysearch_text models.TextField(_(Search text - used only for searching addresses), editableFalse) search_fields [first_name, last_name, line1, line2, line3, line4, state, postcode, country]代码注释直言“This is effectively a poor mans Solr text field”——这是 Oscar 为轻量地址搜索准备的冗余字段把所有可搜索字段用空格拼接后冗余存储到search_text中管理后台admin和 dashboard 搜索地址时只需对这个单字段做icontains匹配无需对多个字段分别查询。注意country在拼接时会被替换为printable_name见get_field_values。派生属性summary / name / salutationAbstractAddress提供了一组只读属性用于展示格式化后的地址salutation称谓 名 姓如Mr John Smithname名 姓summary地址摘要由active_address_fields()用逗号拼接——它合并了称谓与姓名的单行再依次拼接地址行、州、邮编、国家是地址最常用的展示形式__str__直接返回它。这些属性依赖两个字段清单abstract_models.pybase_fields hash_fields [salutation, line1, line2, line3, line4, state, postcode, country]base_fields用于生成展示摘要hash_fields用于生成去重哈希——两套清单在默认实现中相同但子类可以分别覆盖。generate_hash()地址去重的关键UserAddress允许用户保存多个地址但 Oscar 通过哈希机制避免重复地址进入通讯录def generate_hash(self): field_values self.get_address_field_values(self.hash_fields) return zlib.crc32(, .join(field_values).upper().encode(UTF8)) 0xFFFFFFFF实现要点对hash_fields中所有非空字段值空值会被get_address_field_values过滤掉用逗号连接、转大写后做 CRC32 校验和并通过 0xFFFFFFFF保证跨平台结果一致Python 2/3 的 CRC32 取值范围不同。子类AbstractUserAddress在save()中调用它写入hash字段db_indexTrue, editableFalse并通过unique_together (user, hash)加数据库级约束validate_unique()还会给出友好错误“This address is already in your address book”。也就是说哪怕用户换个大小写重复录入也会被判定为同一地址。populate_alternative_model()地址复制的桥梁这是连接“用户通讯录”与“订单快照”的转换工具abstract_models.pydef populate_alternative_model(self, address_model): destination_field_names [field.name for field in address_model._meta.fields] for field_name in [field.name for field in self._meta.fields]: if field_name in destination_field_names and field_name ! id: setattr(address_model, field_name, getattr(self, field_name))它把当前地址实例上所有同名字段的值复制到另一个地址模型实例上跳过id。docstring 明确指出用途结账流程checkout中把用户地址转换为配送地址——用户选中通讯录里的一条地址后Oscar 通过它生成一份独立的ShippingAddress快照之后对通讯录的任何修改都不影响这份快照。AbstractCountryISO 3166 国家表AbstractCountry对应 ISO 3166 国家代码标准abstract_models.py字段设计如下字段说明iso_3166_1_a2两位字母代码如GB主键iso_3166_1_a3三位字母代码如GBR可空iso_3166_1_numeric三位数字代码可空printable_name常用名称如 “United Kingdom”db_indexTruename官方全称如 “United Kingdom of Great Britain and Northern Ireland”display_order展示排序权重数值越大越靠前db_indexTrueis_shipping_country是否为配送可用国家db_indexTrueMeta.ordering为(-display_order, printable_name)——display_order越大越靠前help_text 写明 “Higher the number, higher the country in the list”同权重时按名称字母序这让运营可以把常用国家置顶。此外还提供两个便捷属性codeiso_3166_1_a2的别名和numeric_code对数字代码做前导零补位如840→840、36→036。docstring 提到iso_3166_1_numeric曾经是整数字段历史数据可能缺少前导零因此补位逻辑被保留。三个业务子类UserAddress / ShippingAddress / BillingAddress / PartnerAddressAbstractUserAddress用户的“通讯录”在AbstractShippingAddress基础上再叠加用户归属与默认标记abstract_models.pyuser models.ForeignKey(AUTH_USER_MODEL, on_deletemodels.CASCADE, related_nameaddresses) is_default_for_shipping models.BooleanField(defaultFalse) is_default_for_billing models.BooleanField(defaultFalse) num_orders_as_shipping_address models.PositiveIntegerField(default0) num_orders_as_billing_address models.PositiveIntegerField(default0) hash models.CharField(max_length255, db_indexTrue, editableFalse) date_created models.DateTimeField(auto_now_addTrue)要点默认地址唯一性save()中调用_ensure_defaults_integrity()当新地址被标记为默认配送/账单地址时会先把该用户其他地址的同名默认标记批量置为False保证“每个用户最多一个默认配送地址、一个默认账单地址”。使用频次统计两个num_orders_as_*字段在结账时被累加Meta.ordering [-num_orders_as_shipping_address]让“最常用的地址排在最前”方便用户快速选择。Meta.app_label address其具体模型UserAddress注册在 address 应用中related_nameaddresses让user.addresses可直接访问该用户全部地址。AbstractShippingAddress / AbstractBillingAddress订单快照两者都只继承AbstractAddress额外定义ShippingAddress增加phone_numberPhoneNumberField来自 django-phonenumber-field 库和notes配送备注字段并注册到 order 应用BillingAddress不增加字段仅注册到 order 应用两者都提供order属性通过self.order_set.first()反查关联的订单。app_label order意味着这些表实际归属于 order 应用而它们在 order/models.py 中被具体化注册。这也解释了文档中“其余抽象模型被 order 应用用于提供配送与账单地址模型”的说法。AbstractPartnerAddress合作方地址PartnerAddress用于表示合作方partner如供应商、物流商的地址字段上仅增加一个外键partner models.ForeignKey(partner.Partner, on_deletemodels.CASCADE, related_nameaddresses)app_label partner具体模型注册在 partner/models.py。docstring 指出其典型场景确定美国税负时依赖发货来源地“useful e.g. when determining US tax which depends on the origin of the shipment”这与 Oscar 处理美国税务的指南 how_to_handle_us_taxes.rst 相呼应。关键配置OSCAR_REQUIRED_ADDRESS_FIELDS地址字段的必填规则完全由配置项OSCAR_REQUIRED_ADDRESS_FIELDS驱动默认值定义在 defaults.pyOSCAR_REQUIRED_ADDRESS_FIELDS ( first_name, last_name, line1, line4, postcode, country, )它有两个消费方源码确认模型层abstract_models.py 据此计算POSTCODE_REQUIRED决定邮编是否参与“该填没填”校验表单层forms.py 的AbstractAddressForm.__init__把配置中出现的字段强制设为requiredTrue且UserAddressForm的fields清单first_name、last_name、line1~line4、state、postcode、country、phone_number、notes与配置取交集后生效。自定义示例——假设你的业务要求州/省必填、邮编可选# settings.py OSCAR_REQUIRED_ADDRESS_FIELDS ( first_name, last_name, line1, line4, state, country, )此时POSTCODE_REQUIRED自动变为False表单中postcode恢复为可选且由于校验规则只对“配置中列出”的字段生效整个地址表单的必填约束都会随之调整。这是 Oscar 地址体系“配置驱动校验”的核心用法。表单与 Admin配套的管理能力虽然 address 应用不提供面向用户的视图但它为其他应用提供表单基类并在 admin 中开放管理入口表单forms.pyAbstractAddressForm是地址表单的公共基类被 dashboard 及客户中心customer的地址编辑表单复用UserAddressForm结合PhoneNumberMixin提供电话号码字段的国际化校验实现用户地址表单构造时需传入user并自动绑定到实例。Adminadmin.pyUserAddressAdmin把两个使用次数统计字段设为只读支持按用户名、邮箱、地址行、邮编、电话等搜索并对user启用 autocompleteCountryAdmin提供list_display、按is_shipping_country筛选和按名称/代码搜索。两个模型均通过get_model(address, ...)动态获取保证对 fork 后的自定义模型同样生效。与其他应用的协作关系address 不孤立存在它是结账链路的地基checkout应用在结账流程中通过populate_alternative_model()把UserAddress复制为ShippingAddress/BillingAddress快照相关代码见 checkout/mixins.py、checkout/session.pyorder应用持有ShippingAddress/BillingAddress的具体模型order/models.pypartner应用持有PartnerAddresspartner/models.pydashboard的订单与合作方管理界面通过 address 模型展示与编辑地址见 dashboard/orders/views.py、dashboard/partners/views.py。对应地order.rst、partner.rst、checkout.rst 等应用文档分别从各自视角描述了对地址模型的消费方式。小结回看 address.rst 那句“只提供核心地址模型、不提供视图”其背后的工程智慧在于用抽象模型统一地址行为用具体注册分散业务归属。5 个抽象模型各司其职——AbstractAddress沉淀通用字段、校验与工具方法AbstractCountry承载 ISO 3166 国家数据AbstractShippingAddress/AbstractBillingAddress成为订单不可变快照AbstractUserAddress支撑可变通讯录AbstractPartnerAddress服务合作方。配合POSTCODES_REGEX的国家级邮编校验、generate_hash()去重、OSCAR_REQUIRED_ADDRESS_FIELDS配置驱动校验以及 Oscar 的动态模型覆盖机制开发者可以在此基础上 fork 出完全符合自身业务规则的地址体系。赞分享后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载相关推荐django-oscar 模型定制实战通过 Fork 应用与子类化扩展核心模型django oscar 模型定制实战通过 Fork 应用与子类化扩展核心模型 模型定制是 django oscar 二次开发中最常见也最关键的需求——无论是后端电商PinchTab Lite Engine 与静态优先抓取无 Chrome 的 DOM 捕获架构与 ghost-chrome 演进PinchTab Lite Engine 与静态优先抓取无 Chrome 的 DOM 捕获架构与 ghost chrome 演进 PinchTab 内置了一条后端电商Ryzen AI开发者必看Gemma-3-4B-IT模型ONNX部署全攻略Ryzen AI开发者必看Gemma 3 4B IT模型ONNX部署全攻略 Gemma 3 4B IT模型是专为Ryzen AI优化的ONNX格式模型采用先上一篇TikTok评论采集工具三分钟学会批量导出抖音评论到Excel下一篇Ghost Downloader 3 完整使用指南六种下载协议一个软件搞定创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考