后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载本指南基于 django-oscar 官方贡献文档 docs/source/internals/contributing/coding-style.rst 展开系统梳理了在参与 django-oscar 开发时必须遵循的编码约定包括 PEP8/PEP257 与 Django 官方编码风格的基本要求、make lint等静态检查工具的用法、URL 路径与命名规则、视图类命名范式、_default_manager引用约定以及 HTML 缩进规范。读完本文你将能够按社区一致的标准提交代码、审查 PR并理解这些规范在仓库源码中的真实落地方式。一、总体原则在标准之上保持常识django-oscar 是一个领域驱动domain-driven的 Django 电商框架其代码库横跨数十个 appbasket、catalogue、checkout、dashboard、offer、order 等贡献者众多。为了让整个代码库保持风格统一官方要求贡献者遵循以下三份业界标准规范内容作用范围PEP8Python 代码风格指南缩进、行长、空行、导入顺序、命名等PEP257Docstring 约定模块、类、函数的文档字符串写法Django Coding StyleDjango 官方编码风格Django 项目特有的约定如模板标签、URL 命名等文档同时强调Please follow these conventions while remaining sensible——即遵循这些约定时保持常识判断遇到规范没有覆盖或规范之间冲突的边界情况以可读性和一致性为准。此外官方推荐阅读《Code Like a Pythonista》一书David Goodger 的 PyCon 2007 讲义来培养惯用法的 Python 写作风格。二、静态检查flake8 与 isort 的执行方式文档明确指出仓库使用flake8和isort两个工具来强制实施基础编码标准并给出了统一入口$ make lint在真实仓库中这一命令对应根目录 Makefile 中的linttarget。需要注意的是随着项目演进make lint实际执行的内容已不止 flake8 与 isort还包括black代码格式化与pylint深度静态分析lint: black --check --exclude migrations/* src/oscar/ black --check --exclude migrations/* tests/ pylint setup.py src/oscar/ pylint setup.py tests/其中black --check只检查不修改任何未格式化的文件都会导致make lint失败需要格式化时运行make black对应 Makefilepylint结合了pylint-django插件见 pyproject.toml迁移文件migrations/*被统一排除在 black 检查之外因为迁移代码大多由makemigrations自动生成人工格式化反而会造成噪音。flake8 与 isort 的仓库实际配置虽然 Makefile 的linttarget 已改为 black pylint但 flake8 与 isort 的配置仍然保留在仓库的 setup.cfg 中供 CI 或其他检查流程使用具体如下[flake8] exclude migrations ignore F405,W503,E731 max-complexity 10 max-line-length119 [isort] line_length 79 multi_line_output 4 balanced_wrapping true known_first_party oscar,tests use_parentheses true skip_glob*/migrations/*对这份配置的解读max-line-length119flake8 允许的最长行是 119 字符比 PEP8 默认的 79 更宽与 Django 官方风格一致max-complexity 10单个函数的 McCabe 圈复杂度上限为 10超过即告警从工具层面强制代码保持简单ignore F405,W503,E731忽略三类告警——F405from module import *后变量可能未定义用于 Django 的__init__.py重导出场景、W503换行时二元运算符位于行首、E731lambda 赋值exclude migrations/skip_glob*/migrations/*迁移目录整体跳过检查isort 的known_first_party oscar,tests告诉 isortoscar与tests属于第一方代码导入排序时与第三方包分开multi_line_output 4use_parentheses true多行导入使用括号包裹、每行一个模块的 Vertical Hanging Indent 风格。在后续开发中若希望单独运行这两项检查可以手动执行flake8 src/oscar/ tests/ isort --check-only src/oscar/ tests/三、URL 规范路径形态与命名规则URL 是电商站点最容易累积混乱的地方。django-oscar 文档为 URL 制定了清晰且可记忆的约定这套约定直接反映在 dashboard 各 app 的路由定义中。3.1 路径形态列表用复数、详情用 PK/Slug页面类型约定示例列表页使用复数名词/products/、/notifications/详情页在列表路径上追加 PK 或 slug/products/the-bible/、/notifications/1/创建页以create结尾/dashboard/notifications/create/更新页详情页形态或显式update/dashboard/notifications/3/、/dashboard/notifications/3/update/删除页以delete结尾/dashboard/notifications/3/delete/文档特别说明了两点细节更新页有时与详情页是同一页面如 dashboard 内直接在详情上编辑的场景此时沿用详情页约定即可无需额外update段只有详情与更新确实分离时才使用/update/后缀避免为了统一而统一。3.2 命名规则URL name 使用短横线而非下划线例如catalogue-product-create、catalogue-category-delete而不是catalogue_product_create。这套规则与 Django 官方风格一致短横线在{% url %}模板标签中无需转义即可书写。3.3 源码印证dashboard 路由的真实形态打开 src/oscar/apps/dashboard/catalogue/apps.py可以看到所有约定都落到实处path(products/bulk-action/, self.product_bulk_action_confirm_view.as_view(), namecatalogue-product-bulk-action), path(products/int:pk/, self.product_createupdate_view.as_view(), namecatalogue-product), path(products/create/, self.product_create_redirect_view.as_view(), namecatalogue-product-create), path(products/int:pk/delete/, self.product_delete_view.as_view(), namecatalogue-product-delete), path(, self.product_list_view.as_view(), namecatalogue-product-list), path(categories/create/, self.category_create_view.as_view(), namecatalogue-category-create), path(categories/int:pk/update/, self.category_update_view.as_view(), namecatalogue-category-update), path(categories/int:pk/delete/, self.category_delete_view.as_view(), namecatalogue-category-delete), path(product-type/int:pk/update/, self.product_class_update_view.as_view(), namecatalogue-class-update), path(product-type/int:pk/delete/, self.product_class_delete_view.as_view(), namecatalogue-class-delete),观察这些路由可以归纳出仓库的几条隐含实践复数列表 PK 详情products/是列表products/int:pk/是详情/编辑create/delete作为末段创建与删除动作显式出现在路径末尾URL name 全部使用短横线catalogue-product-create、catalogue-class-update等更新与详情复用同一路由catalogue-product同时承担详情与更新正是文档中dashboard 内详情页即更新页的实例。类似地src/oscar/apps/dashboard/offers/apps.py 中可以看到促销活动的多步向导式路由new/metadata/、new/condition/、new/incentive/、new/restrictions/创建与int:pk/metadata/、int:pk/delete/更新/删除URL name 同样使用短横线offer-metadata、offer-delete、offer-detail。3.4 模板中的引用方式约定在模板侧同样生效。例如产品列表模板 src/oscar/templates/oscar/dashboard/catalogue/product_list.html 中通过{% url dashboard:index %}引用命名空间下的 URL name。由于 dashboard 各 app 的 URL name 统一使用短横线模板中的{% url %}引用非常直白也便于在permissions_map中作为权限键使用见下文第四节中的catalogue-product-create等键名。四、视图类命名%s%sView范式文档给出的视图类命名公式为%s%sView % (class_name, verb)即领域对象名 动作动词 ViewProductUpdateViewOfferCreateViewPromotionDeleteView文档同时说明该范式并不适配所有场景但是一个良好的基础。在仓库中可以找到大量遵循该范式的实例src/oscar/apps/customer/views.pyAddressListView、AddressCreateView、AddressUpdateView、AddressDeleteViewsrc/oscar/apps/customer/wishlists/views.pyWishListCreateView、WishListUpdateView、WishListDeleteViewsrc/oscar/apps/dashboard/catalogue/views.pyProductListView、ProductCreateUpdateView、ProductDeleteView、CategoryCreateView、CategoryUpdateView、CategoryDeleteView。值得注意的两种常见变体复合动词当创建与更新共用一套逻辑时使用复合动词如ProductCreateUpdateView见 views.py其内部用UpdateView同时承载新增与编辑两条路径无动词的详情/列表类ProductDetailViewsrc/oscar/apps/catalogue/views.py、ProductListView等遵循对象 View即可动作语义由Detail/List表达。在 src/oscar/apps/dashboard/catalogue/apps.py 中可以看到这些视图类通过get_class(dashboard.catalogue.views, ProductListView)按名称字符串懒加载因此视图类的命名同时还是应用配置层面的契约——一旦改名必须同步修改apps.py中的引用这也解释了为何规范要强制统一的命名范式。4.1 命名与权限键的一致性细看 apps.py 的 configure_permissions权限映射的键如catalogue-product、catalogue-product-create、catalogue-product-delete同样遵循对象-动作的命名逻辑与视图类名形成一一对应的可读性审查者可以凭名字快速推断权限覆盖的页面。五、Manager 引用约定优先使用_default_manager这是文档中技术性最强的一条约定Use_default_managerrather thanobjects. This allows projects to override the default manager to provide domain-specific behaviour.原因objects是 Django 自动附加的默认 manager 属性名但项目可以通过Meta.default_manager_name或在模型中显式指定 manager 来替换默认 manager此时objects可能不存在或不再是默认。使用_default_manager可以让代码自动跟随项目自定义的默认 manager从而获得领域特定的查询行为。含义_default_manager在查询集QuerySet上没有对应属性必须通过模型类访问即Model._default_manager.filter(...)而不是Model.objects.filter(...)。仓库中大量代码遵循此约定例如src/oscar/apps/basket/reports.pyBasket._default_manager.filter(statusBasket.OPEN)src/oscar/apps/analytics/receivers.pyUserSearch._default_manager.create(useruser, queryquery)src/oscar/apps/catalogue/utils.pyProduct._default_manager.get(**kwargs)src/oscar/apps/basket/views.pyself.voucher_model._default_manager.get(codecode)src/oscar/apps/address/abstract_models.pyself.__class__._default_manager.filter(...)这是通过实例类动态获取默认 manager 的写法。对于需要自定义查询行为的模型django-oscar 还允许通过覆盖默认 manager 的方式扩展这一点可以参考oscar.test.factoriessrc/oscar/test/factories与各 app 的managers.py文件——例如 src/oscar/apps/basket/managers.py 中定义了OpenBasketManager、SavedBasketManager等专门 manager。贡献者写新代码时应继承这一习惯而非硬编码objects。六、HTML 缩进规范文档对模板/HTML 的要求只有一条Please indent with four spaces.即使用4 个空格进行缩进而不是 Tab也不是 2 个空格。这一点贯穿整个模板目录例如 src/oscar/templates/oscar/dashboard/catalogue/product_list.html 中{% block %}内的嵌套均以 4 空格对齐。django-oscar 的模板以oscar/...为命名空间组织在 src/oscar/templates/oscar 下保持统一的缩进有助于模板继承与 override 时的 diff 可读性。七、在真实开发流程中落地这些规范将上述规范串起来一个典型的 django-oscar 贡献流程如下编写代码遵守 PEP8/PEP257、Django 编码风格视图类按%s%sView命名URL 遵循复数列表 / PK 详情 / create / delete约定URL name 用短横线manager 访问用_default_managerHTML 用 4 空格缩进格式化与检查运行make black自动格式化再运行make lint通过 black 检查与 pylint 静态分析若环境同时配置了 flake8 与 isort参考 setup.cfg 的规则可补充执行运行测试项目测试基于 pytest入口为make test对应 Makefile测试代码同样需要通过black --check与pylint检查提交审查审查者依据本规范核对命名、URL 与 manager 用法迁移文件migrations/*通常不在 black 检查范围内无需手工格式化。7.1 与测试体系的配合规范并非空谈仓库测试目录 tests 中大量集成/功能测试本身就是这些约定的验证者例如tests/integration/offer/下的测试通过 URL name 访问页面tests/functional/dashboard/下的测试直接以路径形态如/dashboard/catalogue/products/断言页面可达。新贡献者可以通过阅读这些测试快速理解规范写出来是什么样。结语django-oscar 的编码规范体量不大但每一处都直击协作痛点统一的 URL 形态让路由表可预测统一的视图类命名让懒加载配置get_class可维护_default_manager约定让领域自定义 manager 真正生效。遵循本文的约定既能让你的代码顺利通过make lint与代码审查也能让整个电商框架在长期演进中保持结构的一致性与可读性。赞分享后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载相关推荐CMake变量命名规范从CMAKE_到PROJECT_的命名最佳实践CMake变量命名规范从CMAKE_到PROJECT_的命名最佳实践 在CMake项目开发中变量命名不仅关系到代码的可读性更直接影响项目的可维护性和团队协构建工具开发工具CLICosmos 项目 Kotlin 编码风格指南从命名规范到 Lambda 与类头格式化的完整实践Cosmos 项目 Kotlin 编码风格指南从命名规范到 Lambda 与类头格式化的完整实践 本篇技术指南以 Cosmos 项目的 Kotlin 风格指南教程示例工程Stencil 组件风格指南从文件结构、命名规范到类内代码编排的完整实践Stencil 组件风格指南从文件结构、命名规范到类内代码编排的完整实践 本文以 Stencil 官方仓库根目录下的 STYLE_GUIDE.md https开发工具前端前端构建上一篇OpenDesign Retro 设计系统实战从高对比复古风格到 Token 分层契约的完整解析下一篇Egg 框架深度指南基于 Node.js 与 Koa 的企业级框架构建引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考