后端前端协同办公即时通讯企业应用【免费下载链接】dootaskDooTask是一款开源在线项目任务管理工具提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM文件管理等工具同时消息功能使用非对称加密技术让你的沟通更安全。项目地址https://gitcode.com/gh_mirrors/do/dootask点击查看免费下载DooTask 的 routes/api-map.md 是一份由命令行自动生成的API 路由对照表覆盖了当前仓库全部 329 个 HTTP 接口把每一个 URL 精确映射到对应的控制器方法。本篇文章以这份对照表为骨架结合 routes/web.php、InvokeController.php 与 DocApiMap.php 的源码实现讲清楚三件事DooTask 的 API 为何采用URL 段即方法名的动态路由、这张表是如何被自动生成并保持与代码同步的以及面对这张表时如何快速定位、调试与二次开发你自己的接口。一、这份文档是什么自动生成的 API 路由对照表api-map.md是 DooTask 项目内部维护的接口索引文档其定位有三个鲜明特征自动生成文件头部明确标注此文件由php artisan doc:api-map生成勿手改说明它是构建/发布流程的产物而非手写文档全局覆盖以接口总数329开头按控制器维度分节覆盖用户、项目、对话、文件、上传、汇报、搜索等全部 API 模块一眼定位每一行都是URL | 方法名 | HTTP 方法 | 说明的四列结构方便开发者在看到某个接口调用时立刻反查其控制器实现。对于开发者来说这份表既是接口总清单也是调试排错的起点——前端报错时先按 URL 在表中定位控制器与方法名再去app/Http/Controllers/Api/目录下阅读对应实现即可。二、路由规则URL 段如何映射为控制器方法2.1 三种映射规则对照表开头的路由规则一节给出了 DooTask API 路由的核心约定其根因在 routes/web.php 中可以看到所有 API 统一挂在api前缀 webapi中间件之下用Route::any({controller}/{method}, Controller::class)这种单控制器单路由的方式注册而不是为每个方法单独注册一条路由。URL 与控制器方法的对应关系如下URL 形态映射目标示例api/{controller}/{method}控制器上的{method}()方法api/project/lists→ProjectController::lists()api/{controller}/{method}/{action}{method}__{action}()方法双下划线连接api/project/invite/join→ProjectController::invite__join()固定 method 的三级路由{fixed_method}__{action}()api/file/dav/status→FileDavController::dav__status()2.2 路由的落地执行__invoke 与 __before动态路由最终由控制器基类 InvokeController.php 的__invoke方法统一接管L21-L39public function __invoke($method, $action ) { $app $method ?: main; if ($action) { $app . __ . $action; } // 接口不存在仅 public 方法可作为端点protected/private 为内部方法不暴露为路由 if (!method_exists($this, $app) || !(new \ReflectionMethod($this, $app))-isPublic()) { $msg 404 not found ( . str_replace(__, /, $app) . ).; return Base::ajaxError($msg); } $res $this-__before($method, $action); if ($res true || Base::isSuccess($res)) { return $this-$app(); } else { return is_array($res) ? $res : Base::ajaxError($res); } }关键细节URL 中的{method}、{action}两段在__invoke内被拼成{method}__{action}的方法名再动态调用权限与前置校验的钩子是__before($method, $action)L46-L49基类默认直接返回true各业务控制器可重写它做登录态、权限、参数预处理返回true才放行到真正的业务方法只有 public 方法才会被暴露为接口protected/private方法即使能被method_exists找到也会因ReflectionMethod::isPublic()检查而被拒绝返回404 not found (xxx/yyy).——这既是安全边界也是方法名最多一个双下划线这一限制的根源URL 只有两段拼接后的方法名结构天然只能含一个__。2.3 特殊形态固定 method 路由与自定义 __invoke对照表中的file/dav模块FileDavController是一个特例。在 routes/web.php 中它注册为Route::any(file/dav/{action}, FileDavController::class)-defaults(method, dav);该路由固定了method为davURL 中只透出{action}一段。因此它的接口命名遵循dav__{action}的规律例如api/file/dav/status对应dav__status()、api/file/dav/conflicts对应dav__conflicts()。由于 Laravel 在调用动态控制器时传入参数的顺序与本路由的默认值位置不同FileDavController.php 重写了__invoke来调整参数顺序public function __invoke($action, $method dav) { return parent::__invoke($method, $action); }这解释了为何对照表中file/dav一节的方法名都带dav__前缀也提醒我们表格中的方法名就是你在源码里搜索的准确标识符。2.4 HTTP 方法与any的含义对照表中每行第三列标注 HTTP 方法get/post/any。由于routes/web.php用的是Route::any(...)理论上任何 HTTP 动词都能命中路由表格中的get/post实际来自控制器方法 docblock 中的api {get}/api {post}注释而没有写api注释的方法则统一显示为any如api/project/task/ai_generate、api/system/setting/ai、api/dialog/msg/ai_generate等见 DocApiMap.php 的解析逻辑。因此any并不意味着任意方法都能安全调用而是该方法未在注释中声明 HTTP 动词若要给接口补充语义应在方法 docblock 中补写api {get} api/xxx/yyy 说明。三、自动生成机制doc:api-map 命令的完整原理既然文件头部声明勿手改那么它必然有可靠的重生成途径。生成器是 DocApiMap.php一条命令即可让表格与代码永远同步php artisan doc:api-map成功执行后终端会输出已生成: routes/api-map.md控制器 N 个接口 329 个整个生成管线分四步收集控制器映射collectControllersL44-L67遍历 Laravel 已注册路由表Route::getRoutes()用正则匹配api/{prefix}/{method}形态的 URI从路由动作中取出控制器类名同时识别带defaults[method]的固定 method 路由如file/dav反射扫描方法collectMethodsL75-L105对每个控制器做ReflectionClass反射只保留本类声明、非静态、非__开头的 public 实例方法——这与__invoke的运行时校验规则public 才暴露完全一致保证表格与真实可访问接口一一对应解析接口注释parseApiDocL112-L119用正则api\s\{(\w)}\s(\S)(?:[ \t](.))?从方法 docblock 提取 HTTP 动词与标题缺省时兜底为[any, ]渲染 MarkdownrenderHeader / renderSectionL124-L162按api/{prefix}/{urlMethod}拼接完整 URL__会被替换回/最终写入routes/api-map.md。值得注意的是整个流程不依赖手写清单而是直接反射运行时的路由与控制器因此新增一个 public 方法、改一个api注释重新执行一次命令表格即自动更新——这也是它敢写勿手改的原因手改的痕迹在下一次生成时会被覆盖。四、对照表逐模块导读329 个接口都干了什么以下按表格章节梳理各控制器职责与代表性接口方便按业务域检索。4.1 usersUsersController——账号与个人中心覆盖登录注册login、login/qrcode、reg/needinvite、验证码login/needcode、login/codeimg、login/codejson、资料密码info、editdata、editpass、会员管理与批量导入lists、operation、createuser、import/preview、import、import/template、部门管理department/list、department/add、department/adddeputy、department/sync、签到checkin/get、checkin/save、checkin/list、设备与安全device/list、device/logout、delete/account、key/client以及近年新增的个人化能力个性标签tags/lists、tags/add、tags/recognize、任务浏览历史task/browse、task/browse_save、task/browse_clean、最近访问recent/browse、recent/delete、收藏favorites、favorite/toggle、favorite/remark、个人应用排序appsort、appsort/save。其中login接口同时承担登录与注册通过type参数区分info/managed_departments用于负责人视角切换是 DooTask 多负责人机制的前端入口。4.2 projectProjectController——项目与任务核心这是全表体量最大的模块涵盖项目生命周期lists、one、add、update、transfer移交、adddeputy/deldeputy任命/罢免项目管理员、archived归档、remove、exit、top置顶、sort任务排序、permission/permission/update权限设置任务列表列column/lists、column/add、column/update、column/remove、column/one任务 CRUD 与扩展task/lists、task/easylists、task/one、task/add、task/addsub子任务、task/upgrade子任务升级、task/update、task/copy、task/move、task/archived、task/remove、task/dialog创建/获取任务聊天室、task/content、task/content_history、task/files、task/filedown导出与模板task/export、task/exportoverdue、task/down限管理员task/template_list、task/template_visible跨项目模板、task/template_save、task/template_sort、task/template_default工作流与标签flow/list、flow/save、flow/deletetag/save、tag/sort、tag/delete、tag/listAI 能力task/ai_generate、ai/generate、task/ai_apply采纳 AI 建议、task/ai_dismiss忽略 AI 建议邀请与日志invite、invite/info、invite/joinlog/lists。task/addsub、task/related关联任务与task/related/delete对应任务间的父子、关联关系task/resetfromlog根据日志重置任务则体现了 DooTask 操作留痕、可回溯的设计。4.3 projecttaskhandoffProjectTaskHandoffController——任务流转lists流转记录、options指派人员与权限、assign指派负责人并附带留言三个接口构成任务交接闭环后端实现在 ProjectTaskHandoffService.php并有 ProjectTaskHandoffTest.php 与 ProjectTaskHandoffFeatureTest.php 两组测试保障。4.4 dashboardDashboardController——负责人视角team/stats统计与team/tasks任务列表支撑负责人视角看板与 users 模块的info/managed_departments遥相呼应测试见 DashboardTeamTest.php。4.5 systemSystemController——系统设置与通用能力设置类setting全局设置、setting/email、setting/meeting、setting/ai、setting/aibot、setting/checkin、setting/apppush、setting/thirdaccess、setting/file均限管理员运维类version、get/info、get/ip、get/cnip、get/updatelog、license、demo、prefetch预加载资源通用能力imgupload、imgview、fileupload上传/浏览图片与文件、email/check邮件测试、checkin/export、checkin/down签到导出、column/template创建项目模板、microapp_menu自定义应用菜单、priority任务优先级。4.6 licenseLicenseController——在线授权email/send、login、login/confirm、trial试用、status、refresh、logout一套完整的授权生命周期接口对应 OnlineLicense.php 与命令 OnlineLicenseRenew.php。4.7 dialogDialogController——即时消息IMDooTask 的 IM 能力全部集中于此是全表接口最密集的模块之一会话lists、beyond、search、search/tag、one、user、todo、top、hide、tel、open/user、open/event、config、config/save消息收发msg/list、msg/latest、msg/one、msg/sendtext、msg/sendnotice、msg/sendtemplate、msg/sendapprove审批卡片、msg/sendrecord/msg/convertrecord语音、msg/sendfile/msg/sendfiles/msg/sendfileid、msg/sendtaskid、msg/sendanon匿名、msg/sendbot机器人、msg/send_ai_assistant、msg/sendlocation、msg/stream通知成员监听消息操作msg/read、msg/unread、msg/dot、msg/withdraw撤回、msg/forward/msg/mergeforward转发/合并转发、msg/emoji、msg/tag标注、msg/todo/msg/todolist/msg/todoremind/msg/done待办、msg/mark、msg/silence免打扰、msg/top置顶、msg/color、msg/readlist、msg/detail、msg/download、msg/voice2text、msg/translation翻译、msg/wordchain接龙、msg/vote投票群组group/add、group/edit、group/adduser、group/deluser、group/transfer、group/adddeputy/group/deldeputy、group/disband、group/searchuserAI 会话session/create、session/list、session/open、session/rename。其中msg/sendfile、msg/sendfiles属于上传入口而upload/*模块则是大文件分片上传的统一通道见 4.9。msg/webhookmsg2ai与sticker/search在线表情则是与外部系统打通的能力点。4.8 fileFileController / FileDavController——文件与 WebDAV文件模块同时承载两套协议业务 APIFileControllercollaboration/lists、collaboration/download协作文件lists、one、search、add、copy、move、remove文件/文件夹 CRUDcontent、content/save、content/history、content/restore内容与历史office/token、content/office在线 Office 编辑share、share/update、share/out共享link链接、download/pack打包下载、fetch按路径取文本内容WebDAV 管理FileDavControllerdav/status、dav/credentials、dav/create、dav/revoke、dav/delete、dav/adminsetting、dav/adminstatus、dav/conflicts、dav/conflictrename、dav/userrevoke配合 routes/web.php 中独立的dav/{path?}协议入口PROPFIND/PUT/MOVE/LOCK 等使用设计细节可参考 docs/webdav-design.md。4.9 uploadUploadController——分片上传init启动会话支持秒传/续传命中、chunk上传分片、merge合并入库、cancel取消会话四段式流程是文件消息、任务附件、图片等所有场景的大文件统一通道。其 docblock 注释见 UploadController.php写明小于 10MB 的小文件不走此接口前端直接调用各场景老接口实现透明降级。会话元数据存于 Rediscancel会清理分片目录与索引。4.10 reportReportController——工作汇报my我发送的、receive我接收的、store保存并发送、template模板生成、detail、mark、share分享到消息、last_submitter、unread、read批量已读以及 AI 能力analysave保存汇报 AI 分析。4.11 其余模块publicPublicController仅checkin/install、checkin/report两个无需登录的开放端点签到打卡场景assistantAssistantControllerAI 助手授权与能力接口——auth生成授权码、modelsAI 模型、match_elements元素向量匹配、log/search知识库检索日志、feedback/save反馈、operation/dispatch与operation/result页面操作派发、session/list、session/save、session/deletecomplaintComplaintControllerlists、submit、action构成举报投诉处理闭环searchSearchControllercontact、project、task、file、message五个维度打通全局智能搜索后端配合 Manticore 同步见 SyncMsgToManticore.php 等命令appsAppsControllerbadge/set应用密钥鉴权设置角标、badge/clear当前用户 token 鉴权清除角标、badge/list拉取角标testTestController测试专用端点表中仅保留节标题。五、api 注释表格的数据源与 apiDoc 兼容对照表中每一行的 HTTP 方法与说明源头是控制器方法 docblock 里的api注释例如 UsersController.php 的登录接口/** * api {get} api/users/login 登录、注册 * * apiVersion 1.0.0 * apiGroup users * apiName login * * apiParam {String} type 类型 * - login:登录默认 * - reg:注册 * apiParam {String} email 邮箱 * apiParam {String} password 密码 * apiParam {String} [code] 登录验证码 * apiParam {String} [code_key] 验证码通过key验证 * apiParam {String} [invite] 注册邀请码 * * apiSuccess {Number} ret 返回状态码1正确、0错误 * apiSuccess {String} msg 返回信息错误描述 * apiSuccess {Object} data 返回数据同获取我的信息接口 */ public function login()这套注释完全兼容 apiDoc 规范仓库内 apidoc.md 提供了api、apiBody、apiParam、apiSuccess等全部标签的速查说明apidoc.json 是 apiDoc 的工程配置name: API、title: APP接口、version: 1.0.0。此外 apidoc.php 是一个维护脚本可为各控制器api注释统一追加/移除两位宽度的顺序编号01.、02.…只处理 get/post 注释且跳过已有编号便于 apiDoc 输出稳定的接口排序。理解这条数据链路后如何新增一个接口并让它出现在对照表中的答案就清晰了在控制器里新增 public 方法并写好api注释然后执行php artisan doc:api-map重新生成表格。六、实践指南用好这张表进行开发与排错6.1 新增接口的标准流程在app/Http/Controllers/Api/下对应控制器中新增public方法或{method}__{action}形态的复合方法并在 docblock 中按api {get|post} api/xxx/yyy 说明的格式声明接口若接口需要登录、权限或参数预处理重写/复用基类的__before($method, $action)钩子见 InvokeController.php执行php artisan doc:api-map刷新 routes/api-map.md确认新接口出现在对应分节前端直接按api/{method}/{action}的 URL 调用即可无需在 routes 中新增路由routes/web.php中每个控制器只注册两行通配路由。6.2 排查 404 的三种典型原因当接口返回404 not found (xxx/yyy).时按以下顺序检查方法可见性目标方法是否为 publicprotected/private方法不会被__invoke暴露InvokeController.php方法名与 URL 的对应{method}/{action}会拼接为{method}__{action}URL 中多余的/段会导致方法名不匹配——这也是路由最多两段、方法名最多一个双下划线约束的由来控制器归属URL 第一段必须对应routes/web.php中已注册的控制器前缀且该方法存在于该控制器内api/project/xxx只会去ProjectController找。6.3 作为接口文档的三种用法前端联调按 URL 定位方法名 → 阅读源码中的apiParam确认入参 → 参照apiSuccess处理返回ret为 1 成功、0 失败data为业务数据权限审查表格中标注限管理员的接口如users/lists、system/setting/email、project/task/export在源码中均有对应鉴权逻辑可作为安全巡检清单版本比对php artisan doc:api-map生成的接口总数329可作为版本间的接口增量基线升级时对比新旧表格即可发现变更。结语DooTask 的 API 设计有一个贯穿始终的思路用统一约定代替海量路由注册。api/{controller}/{method}[/{action}]的 URL 结构、{method}__{action}的方法命名、api注释驱动的文档生成三者环环相扣让接口总数 329的庞大体系依然保持新增接口零路由成本、文档永远与代码同步的维护体验。这张 api-map.md 既是导航地图也是理解整个后端控制层架构的最佳切入点——读懂它你就能在 DooTask 的代码库中快速找到任何一个功能的实现入口。赞分享后端前端协同办公即时通讯企业应用【免费下载链接】dootaskDooTask是一款开源在线项目任务管理工具提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM文件管理等工具同时消息功能使用非对称加密技术让你的沟通更安全。项目地址https://gitcode.com/gh_mirrors/do/dootask点击查看免费下载相关推荐Redoc中的动态路由根据API自动生成路由Redoc中的动态路由根据API自动生成路由 引言 在现代API开发中动态路由是一个关键功能它能够根据API规范自动生成导航结构极大地提升了API文档的API设计文档前端Antigravity-Manager 模型重映射链路深度解析静态路由与动态账号回退机制Antigravity Manager 模型重映射链路深度解析静态路由与动态账号回退机制 本篇技术指南以 docs/model remapping logicLLM 网关API网关AI 应用后端UI-Router动态路由生成从API获取路由配置实现UI Router动态路由生成从API获取路由配置实现 你是否遇到过这样的困扰在开发单页应用时路由配置写死在代码中每次新增页面都要修改路由并重新部署特前端路由上一篇WinPython 3.3.2.3 发行版全解析包清单、科学计算软件栈与版本变更溯源下一篇Magic in Ten Mins从零跑通 29 篇函数式编程魔法练习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
