后端开发工具调试器【免费下载链接】django-debug-toolbarA configurable set of panels that display various debug information about the current request/response.项目地址https://gitcode.com/gh_mirrors/dj/django-debug-toolbar点击查看免费下载Django Debug Toolbar 以面板Panel为单位组织全部调试信息每个请求的耗时、SQL、模板、缓存、请求变量等数据都由独立面板采集与渲染。本文以 面板官方文档 为主体逐一点明 16 个内置面板的职责与适用场景、15 个第三方面板的接入方式并结合 Panel 基类源码 与 默认面板配置 深入讲解面板的启用机制与第三方面板的完整开发 API帮助你在调试 Django 应用时快速选对面板并能为自己的工具链编写可插拔面板。内置面板总览工具栏随包内置了 16 个面板默认全部注册在DEBUG_TOOLBAR_PANELS中。从源码 debug_toolbar/settings.py 的PANELS_DEFAULTS可以看到完整默认清单PANELS_DEFAULTS [ debug_toolbar.panels.history.HistoryPanel, debug_toolbar.panels.versions.VersionsPanel, debug_toolbar.panels.timer.TimerPanel, debug_toolbar.panels.settings.SettingsPanel, debug_toolbar.panels.headers.HeadersPanel, debug_toolbar.panels.request.RequestPanel, debug_toolbar.panels.sql.SQLPanel, debug_toolbar.panels.staticfiles.StaticFilesPanel, debug_toolbar.panels.templates.TemplatesPanel, debug_toolbar.panels.alerts.AlertsPanel, debug_toolbar.panels.cache.CachePanel, debug_toolbar.panels.signals.SignalsPanel, debug_toolbar.panels.tasks.TasksPanel, debug_toolbar.panels.community.CommunityPanel, debug_toolbar.panels.redirects.RedirectsPanel, debug_toolbar.panels.profiling.ProfilingPanel, ]其中RedirectsPanel 与 ProfilingPanel 默认处于注册但禁用inactive状态原因是DEBUG_TOOLBAR_CONFIG的默认值DISABLE_PANELS包含了它们# 源码debug_toolbar/settings.py 中的 CONFIG_DEFAULTS DISABLE_PANELS: { debug_toolbar.panels.profiling.ProfilingPanel, debug_toolbar.panels.redirects.RedirectsPanel, },各面板的功能定位如下表面板类路径展示内容默认状态HistoryHistoryPanel请求历史列表可切换查看历史请求的统计快照启用VersionsVersionsPanelPython、Django 及已安装应用的版本号启用TimerTimerPanel请求总耗时始终排在第一个面板启用SettingsSettingsPanelsettings.py中的全部设置项启用HeadersHeadersPanelHTTP 请求/响应头及部分 WSGI 环境值启用RequestRequestPanelGET/POST、cookie、session 变量启用SQLSQLPanelSQL 查询、执行耗时、EXPLAIN 链接、重复/相似查询启用Static filesStaticFilesPanel使用的静态文件及其来源位置经由 staticfiles finders启用TemplatesTemplatesPanel渲染过的模板、上下文与模板路径启用AlertsAlertsPanel预定义问题的告警如含文件输入却未设置enctypemultipart/form-data的表单启用CacheCachePanel缓存调用次数、命中/未命中、耗时启用SignalsSignalsPanel信号及其接收者列表启用TasksTasksPanel请求期间通过django.tasks框架排队的任务启用需 Django 6.0CommunityCommunityPanel指向 Django Debug Toolbar 社区资源的面板启用RedirectsRedirectsPanel拦截 3xx 重定向重定向前先展示调试页注册但默认禁用已弃用ProfilingProfilingPanel请求处理过程的函数级性能剖析注册但默认禁用关于面板的启用/禁用逻辑源码 Panel.enabled 属性 给出了明确规则浏览器 cookiedjdt面板类名如djdtSQLPanel的值优先于一切配置——这就是界面上勾选/取消勾选面板后记住偏好的实现cookie 未设置时以DISABLE_PANELS集合判断面板全路径是否被禁用若面板类名位于某个panel子模块中如sql包的SQLPanel禁用配置允许写完整路径也允许写省略panel的路径。另外enabled属性还会检查异步兼容性若当前请求是 ASGI 请求而面板未声明is_async True该面板会自动禁用因此 tests/panels/test_async_panel_compatibility.py 专门对各面板的 async 兼容性做了校验。History 面板debug_toolbar.panels.history.HistoryPanel展示已发起请求的历史并允许切换到任一历史请求的快照查看其统计数据。两个值得注意的限制若配置项RENDER_PANELS设为True面板随主请求渲染而非 Ajax 加载History 面板会被禁用。源码中 HistoryPanel.enabled 直接叠加了这一判断return super().enabled and not self.toolbar.should_render_panels()若服务器以多进程方式运行History 面板同样无法工作内存中的 store 无法跨进程共享。从源码结构看History 面板通过get_headers在响应中写入djdt-request-id头受OBSERVE_REQUEST_CALLBACK配置控制前端据此把新请求登记到历史列表中它自己声明is_historical False不会把自己重复收录进历史快照。SQL 面板debug_toolbar.panels.sql.SQLPanel记录请求期间执行的每条 SQL、执行耗时并提供对单条查询执行EXPLAIN的链接对应 sql 面板视图 中的sql_select/、sql_explain/、sql_profile/三个路由。其采集机制是游标包装enable_instrumentation 对django.db.connections中每个连接调用wrap_cursor实现在 tracking.py并在连接上挂_djdt_logger请求结束再由disable_instrumentation摘除。面板还会做两件很有实用价值的事按raw_sql与参数对查询分组标出相似查询与重复查询并着色generate_stats 中的分组逻辑超过SQL_WARNING_THRESHOLD默认 500 毫秒见 配置默认值的查询被标记为慢查询。Cache 面板debug_toolbar.panels.cache.CachePanel统计缓存调用命令表列出add/get/set/get_or_set/touch/delete/clear等方法顺序即由 WRAPPED_CACHE_METHODS 决定。实现方式是 monkey patchready() 类方法 在应用启动时包装CacheHandler.create_connection之后每次请求的enable_instrumentation再把当前线程/async 任务中已初始化的连接打上补丁。文档中有两点使用提示值得保留它与 Django 的 per-site 缓存机制update_cache中间件不兼容基于cache.get()返回值的命中/未命中统计不一定准确——从 _store_call_info 源码 看命中判定就是返回值是否等于 default 参数因此当缓存中存储的合法值恰好是Nonedefault时会被误判为未命中。社区正在讨论改进该跟踪逻辑。Redirects 面板已弃用debug_toolbar.panels.redirects.RedirectsPanel自 6.0 版本起被标记为弃用将在未来版本移除——History 面板现在已经能够查看重定向请求的调试数据。该面板启用后的行为是拦截 3xx 响应源码判断条件为300 status_code 400且存在Location头见 _process_response插入一个中间页让你能在浏览器跳转前先看到完整调试信息页面中提供指向重定向目标的链接。由于不调试重定向时这个拦截页很碍事它默认注册但不启用。如需启用可在DEBUG_TOOLBAR_CONFIG[DISABLE_PANELS]中移除它如需深度定制可继承RedirectsPanel并覆写get_interception_response方法直接操纵拦截响应然后在settings.py的DEBUG_TOOLBAR_PANELS中替换原类。Profiling 面板debug_toolbar.panels.profiling.ProfilingPanel展示请求处理过程的函数调用剖析。实现上非常直接process_request 用cProfile.Profile().runcall(...)包裹整个后续处理链请求结束后用pstats.Stats构建调用树。使用限制与文档一致均有源码依据Python 3.12 及以上版本需用python manage.py runserver --nothreading运行——剖析器与并发请求无法共存cProfile是线程本地资源多线程下无法归因若项目定义了settings.BASE_DIR面板会把该目录下的项目代码全部纳入展示函数所在文件位于BASE_DIR内、且路径中不含/site-packages/或/dist-packages/即算项目代码见 FunctionCall.is_project_func相关可调参数默认值来自 CONFIG_DEFAULTSPROFILER_CAPTURE_PROJECT_CODE默认True是否收录全部项目代码、PROFILER_MAX_DEPTH默认 10调用树最大深度、PROFILER_THRESHOLD_RATIO默认 8累计时间低于总时长 1/8 的分支会被裁剪。其余内置面板速览Versionsversions.VersionsPanel显示 Python、Django 版本以及尽可能获取的已安装应用版本。Timertimer.TimerPanel请求计时器。注意 DebugToolbar.enabled_panels 会把 TimerPanel 强制排到最前以便它测量工具栏自身处理在内的完整耗时。Settingssettings.SettingsPanel列出settings.py中的全部配置项。Headersheaders.HeadersPanel显示 HTTP 请求与响应头以及部分 WSGI 环境值。文档特别提醒位于工具栏中间件之前的中间件所设置的响应头不会出现在面板里WSGI 服务器自身也可能添加Date、Server等响应头。Requestrequest.RequestPanel展示 GET/POST/cookie/session 变量。Static filesstaticfiles.StaticFilesPanel显示已使用静态文件及其位置经由staticfilesfinders 查找。Templatestemplates.TemplatesPanel显示已使用的模板、上下文与模板路径。Alertsalerts.AlertsPanel对预定义情形发出告警例如响应中存在文件输入却缺少enctypemultipart/form-data属性的表单。Signalssignals.SignalsPanel列出信号与接收者。Taskstasks.TasksPanel展示请求期间使用 Django 内置任务框架django.tasks排队的任务。注意该面板要求 Django 6.0。Communitycommunity.CommunityPanel提供指向 Django Debug Toolbar 社区资源的链接。面板的加载与渲染机制理解面板如何被装载有助于正确扩展工具栏。从 DebugToolbar 构造器 可以看到加载顺序通过 get_panel_classes 读取DEBUG_TOOLBAR_PANELS未设置时用PANELS_DEFAULTS见 get_panelsimport_string逐个导入面板类并缓存到类属性_panel_classes以逆序实例化并层层包裹process_request只有panel.enabled为真的面板才参与请求处理链面板自身的路由由get_urls()提供统一挂到工具栏 URL 命名空间下get_urls 汇总逻辑。此外get_panels 中还保留了一段兼容性处理如果用户在DEBUG_TOOLBAR_PANELS里残留已移除的debug_toolbar.panels.logging.LoggingPanel它会被自动剔除并发出DeprecationWarning——迁移旧配置时可以在日志中直接看到提示。面板内容默认通过 Ajax 按需加载RENDER_PANELS为None面板统计数据的存取走record_stats/get_stats实现数据同时写入内存 stats 与 store这正是历史快照能跨请求恢复的基础。第三方面板注意第三方面板不在 Django Debug Toolbar 官方支持范围内。维护者会维护一份列表但无法为每个面板的质量背书问题请反馈给面板作者。以下是文档收录的常用第三方面板按面板类路径接入DEBUG_TOOLBAR_PANELS面板类路径功能Flame Graphspyflame.djdt.panel.FlamegraphPanel用火焰图可视化请求的性能剖析LDAP Tracingwindows_auth.panels.LDAPPanel请求期间的 LDAP 操作耗时、请求/响应消息、接收条目、写变更、堆栈跟踪与错误调试Line Profilerdebug_toolbar_line_profiler.panel.ProfilingPanel将line_profiler的行级剖析输出整合进面板Mailmail_panel.panels.MailToolbarPanel捕获并展示应用发出的邮件Memcachememcache_toolbar.panels.memcache.MemcachePanel或memcache_toolbar.panels.pylibmc.PylibmcPanel跟踪 memcached 使用情况支持 pylibmc 与 memcache 两种库MongoDBdebug_toolbar_mongo.panel.MongoDebugPanel增加 MongoDB 调试信息MrBenn Toolbar Pluginmrbenn_panel.panel.MrBennPanel在 IDE 中直接打开模板文件与视图还需把mrbenn_panel加入INSTALLED_APPSNeo4jneo4j_panel.Neo4jPanel跟踪 Neo4j REST API 调用兼容 neo4django 与 neo4jrestclientPymplerpympler.panels.MemoryPanel显示进程内存信息虚拟大小、常驻集大小及当前请求的模型实例Request Historyddt_request_history.panels.request_history.RequestHistoryPanel在多个请求间切换查看统计并支持查看 AJAX 请求统计Requestsrequests_panel.panel.RequestsDebugPanel列出使用requests库发出的 HTTP 请求Template Profilertemplate_profiler_panel.panels.template.TemplateProfilerPanel展示模板渲染耗时及其在时间轴上的分布轻量、兼容复用线程的 WSGI 服务器Template Timingstemplate_timings_panel.panels.TemplateTimings.TemplateTimings展示 Django 应用的模板渲染时间VCS Infovcs_info_panel.panels.GitInfoPanel显示应用的版本控制状态修订号、分支、最近提交日志等uWSGI Statsdjango_uwsgi.panels.UwsgiPanel显示 uWSGI 统计workers、applications、spooler jobs 等添加面板只需把上述类路径追加到你的DEBUG_TOOLBAR_PANELS列表如需移除内置面板或调整顺序同样编辑该列表即可详见 配置文档 的DEBUG_TOOLBAR_PANELS一节。第三方面板开发 API第三方面板必须继承debug_toolbar.panels.Panel遵循下述公共 API。除特别注明外所有方法都是可选的默认实现为空操作或返回空值。面板可以自带模板、静态文件和视图当前没有公开的 CSS API。关键属性属性默认行为nav_title侧边栏标题默认回退到titlenav_subtitle侧边栏副标题默认为空串如 SQL 面板用它显示N queries in Xmshas_content面板能否全屏展示设为False时只在侧边栏显示此时title可不实现title全屏展示的标题必须实现除非has_content为Falsetemplate渲染content所用模板必须实现除非has_content为False或覆写contentcontent默认实现为render_to_string(self.template, self.get_stats())record_stats存的数据会进入模板上下文scripts面板全屏内容所需的 JS 文件列表默认[]is_async声明True后面板才能处理 ASGI 请求基类默认为False从源码结构看panel_id默认取类名classproperty因此子类命名即面板标识无需额外注册。生命周期方法ready()类方法早期初始化只放无论面板是否启用都必须执行且幂等的逻辑如 CachePanel 在此一次性 patchCacheHandler.create_connectionenable_instrumentation()/disable_instrumentation()启用/停用昂贵的采集monkey patch、注册信号接收者等二者都应幂等异步面板可另加aenable_instrumentationprocess_request(request)类似 Django 中间件的请求处理钩子在此保存数据record_stats或返回新响应generate_stats(request, response)响应阶段的收尾处理后处理数据并record_statsgenerate_server_timing(request, response)生成 W3C Server-Timing 统计get_headers默认会把record_server_timing记录的数据拼成Server-Timing响应头get_headers 实现示例格式SQLPanel_sql_time;dur0;descSQL 0 queriesget_urls()类方法返回面板自有视图的 URLPattern 列表run_checks()类方法接入 Django checks 体系返回CheckMessage列表校验集成配置。面板视图的装饰器第三方面板自定义视图必须使用debug_toolbar.decorators.require_show_toolbar——阻止未授权访问视图即不满足SHOW_TOOLBAR_CALLBACK时返回 404该装饰器 同时兼容 async 视图debug_toolbar.decorators.render_with_toolbar_language——让视图渲染的内容使用TOOLBAR_LANGUAGE配置的语言而非LANGUAGE_CODE实现 即language_override(lang)上下文。JavaScript API面板模板应自行包含所需的 JS 文件。工具栏提供以下通用方法djdt.close // 关闭最顶层窗口/面板/工具栏 djdt.cookie.get(key) // 读取 cookie 值 djdt.cookie.set(key, value, options) // options 支持 expires、path另支持 domain、secure、samesite // 未提供 samesite 时默认 lax djdt.hide_toolbar // 关闭所有面板并隐藏工具栏 djdt.show_toolbar // 显示工具栏可在全量重渲染 DOM 后重新挂回工具栏 // 例如使用 HTMX boosting 时事件面板渲染完成时会触发djdt.panel.render事件事件对象带有detail.panelId标识刚加载的面板。编写自定义脚本处理面板 HTML 时通常要监听它。以CustomPanel为例参考 utils.js 提供的工具函数import { $$, getDebugElement } from ./utils.js; function addCustomMetrics() { // 在这里处理/追加自定义指标。 // 注意由于文件是异步加载的要处理该函数被调用两次的情况。 } const djDebug getDebugElement(); $$.onPanelRender(djDebug, CustomPanel, addCustomMetrics); // 由于面板脚本是异步加载的上面的监听注册可能晚于 // djdt.panel.render 事件触发所以这里再手动调用一次渲染函数。 addCustomMetrics();完整的配置项说明DEBUG_TOOLBAR_PANELS、DEBUG_TOOLBAR_CONFIG及其各键的默认值见 配置文档面板行为的大量测试用例可参考 tests/panels 目录例如 test_sql.py、test_cache.py、test_history.py 与 test_custom.py可作为自定义面板实现的参照实现。赞分享后端开发工具调试器【免费下载链接】django-debug-toolbarA configurable set of panels that display various debug information about the current request/response.项目地址https://gitcode.com/gh_mirrors/dj/django-debug-toolbar点击查看免费下载相关推荐Django Debug Toolbar 面板功能详解Django Debug Toolbar 面板功能详解 什么是Django Debug Toolbar面板 Django Debug Toolbar 是一个强大后端开发工具调试器django-debug-toolbar扩展开发自定义面板实现教程django debug toolbar扩展开发自定义面板实现教程 django debug toolbar是Django项目必备的调试工具通过自定义面板可后端开发工具调试器django-debug-toolbar高级面板代码覆盖率分析django debug toolbar高级面板代码覆盖率分析 引言 在Django开发过程中了解代码执行情况和性能瓶颈至关重要。django debug后端开发工具调试器上一篇ComfyUI极速出图三步走Boogu-Image Turbo模型新手友好实战指南下一篇tsParticles Salad 调色板实战指南一行 palette 配置接入健康系绿色粒子配色创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
