技能使用指南

moodle-external-api-development（Moodle外部API开发）Skill 究竟能帮你做什么？

想为Moodle插件快速开发合规的外部Web服务API？Moodle外部API开发Skill按官方三方法模式生成代码，覆盖参数校验、权限控制、事务处理、服务注册与curl测试全流程，内置常见陷阱与调试清单，帮PHP开发者少走弯路。立即了解安装与使用方法。

Moodle外部API开发Skillmoodle-external-api-development
10 个章节 约 17 分钟阅读 AI 智能生成

Moodle外部API开发Skill：让AI按Moodle官方规范生成可上线的外部Web服务

  • 一句话定位：这不是一个查文档的工具，而是一位"懂Moodle外部API框架"的结对开发助手，从类文件结构、参数定义、权限校验到服务注册，全程按官方三方法模式产出代码。
  • 核心机制固定：严格遵循 execute_parameters() → execute() → execute_returns() 三方法模式，避免"能跑但不符合规范"的野路子代码。
  • 覆盖全链路：参数类型与结构、能力与上下文校验、参数化SQL、事务处理、错误日志、services.php 注册、curl/AJAX 测试，一条链路打通。
  • 内置踩坑经验：函数未找到、无效参数值、SQL注入、权限被拒绝、事务死锁等高频问题，技能内直接给出排查清单。
  • 适合谁用：Moodle插件开发者、高校与企业LMS运维团队、要把Moodle能力开放给App或第三方系统的集成人员。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 Moodle外部API开发Skill
技能英文名 moodle-external-api-development
技能ID 12178
解决的核心问题 Moodle 外部 Web 服务 API 开发门槛高、规范多、易踩坑，开发者常常在命名空间、参数结构、能力校验和服务注册之间反复试错

Moodle 的插件体系有自己的一套"隐性规则"：类必须继承 external_api，命名空间必须写成 local_插件名\external，参数必须用 external_value 包装，返回值结构必须与 execute() 返回内容严格一一对应，注册还要写进 db/services.php 并清缓存。任何一环写错，前端拿到的就是"函数未找到"或"检测到无效参数值"。

这个技能的价值在于：它把上述规范打包成一份可执行的开发指南，让你用自然语言描述需求，AI 就按 Moodle 官方模式产出结构化代码，而不是产出一份"看起来像 PHP、但 Moodle 不认"的东西。

一键安装的思路与步骤

安装环节的具体命令与入口因承载平台而异，此处给出通用流程，具体的安装命令、下载地址与账号要求请以官方说明为准：

  1. 确认安装前提：你的使用环境需要已经接入了支持 AI 技能的宿主（例如支持加载 Skill 的 AI 编程助手或对话客户端）；同时你本人需要有基础的 Moodle 插件开发环境（一个可运行的 Moodle 站点、代码目录写权限、管理员账号用于清缓存和配置 Web 服务）。
  2. 检索技能：在技能市场或技能列表中以技能ID 12178 或英文名 moodle-external-api-development 检索该技能。
  3. 执行安装：点击安装/添加按钮，将技能挂载到当前会话或项目工作区。若平台支持项目级配置，建议在 Moodle 插件代码仓库根目录下启用，便于 AI 读取现有插件结构。
  4. 验证是否生效：新建对话，提问"请说明 Moodle 外部 API 的三个必需方法分别是什么，以及类应该放在哪个目录"，如果回答中出现 execute_parameters()、execute()、execute_returns() 与 /local/yourplugin/classes/external/ 路径，说明技能已正确加载。
  5. 二次验证：再让它"写一个获取某用户在某课程中测验尝试次数的读类型 API"，观察输出是否包含 defined('MOODLE_INTERNAL') || die();、require_once("$CFG->libdir/externallib.php"); 和 use external_api; 等必要骨架，这些是该技能正常工作的强信号。

该技能的主要功能和特点

  • 三方法模式强制落地：任何 API 需求都会被拆解为参数定义、业务逻辑、返回结构三段，杜绝"只写 execute 就交付"的半成品。
  • 参数类型体系全覆盖：支持 PARAM_INT、PARAM_TEXT、PARAM_RAW、PARAM_BOOL、PARAM_FLOAT、PARAM_ALPHANUMEXT 等常用类型，并区分 external_value（单值）、external_single_structure（命名对象）、external_multiple_structure（数组）三种结构，同时处理 VALUE_REQUIRED、VALUE_OPTIONAL、VALUE_DEFAULT 三种取值标志。
  • 安全默认开启：生成代码时会自动带上 validate_parameters() 参数校验、validate_context() 上下文校验、require_capability() 能力校验，以及占位符参数化的数据库查询，从源头上规避注入风险。
  • 服务注册一步到位：直接给出 db/services.php 的 $functions 与 $services 写法，包含 classname、methodname、type（read/write）、ajax、capabilities 等关键键位说明。
  • 错误处理与日志范式：提供带时间戳的 log_debug() 私有方法模板，配合 try-catch 分层捕获 invalid_parameter_exception、moodle_exception 与通用 Exception，并在致命错误时记录最后执行的 SQL 与堆栈跟踪。
  • 高级场景覆盖：事务管理（start_delegated_transaction / allow_commit / rollback）、课程模块创建（add_course_module + quiz_add_instance + course_add_cm_to_section）、基于组的可用性限制（availability JSON 条件）、按标签随机抽题（联表 question_versions、question_bank_entries、tag_instance）。
  • 可测试、可排错：内置 Web 服务测试客户端、curl 调用、core/ajax 前端调用三种验证路径，并附带一份调试清单与常见陷阱对照表。
  • 和普通工具比强在哪：普通代码补全只会根据上下文猜下一行；这个技能知道 Moodle 的"规矩"——它知道返回结构必须与 execute 返回完全一致，知道改了 services.php 必须清缓存，知道 type 写错会导致写操作被当成读操作。

如何使用该技能？

以下为推荐的分步使用流程。

步骤 1：描述清楚你的 API 意图

不要只说"帮我写个 Moodle API"，而要给出：属于哪个插件类型（local_ 还是 mod_）、插件名、读还是写、输入输出字段。示例提问：

我要在 local_userlog 插件里加一个只读接口，输入 userid 和 courseid，返回该用户在该课程中的测验尝试总数。

步骤 2：让 AI 输出类骨架与参数定义

技能会给出命名空间 local_userlog\external、安全行、externallib.php 引入，以及 execute_parameters() 中两个 PARAM_INT 必填参数的写法。

步骤 3：审查业务逻辑段落

重点看三件事：是否先 validate_parameters()、是否用 context_course::instance() 取得上下文并 validate_context()、SQL 是否全部使用 :userid、:courseid 这类占位符。技能给出的示范写法是：

$sql = "SELECT COUNT(*) AS quiz_attempts
        FROM {quiz_attempts} qa
        JOIN {quiz} q ON qa.quiz = q.id
        WHERE qa.userid = :userid AND q.course = :courseid";

注意表名使用 {} 包裹，这是 Moodle 支持表前缀的标准写法。

步骤 4：核对返回结构一致性

execute_returns() 必须与 execute() 的返回数组字段完全对齐。上例中 execute 返回 ['quiz_attempts' => (int)$attempts]，返回结构就应声明一个 quiz_attempts 的 PARAM_INT 字段。

步骤 5：注册服务并清缓存

把函数写入 db/services.php，记住 methodname 永远是 execute，读接口 type 填 read。修改后必须到 站点管理 > 开发 > 清除所有缓存，否则会出现"函数未找到"。

步骤 6：实际调用验证

按技能提供的 curl 模板，先通过 /login/token.php 取令牌，再向 /webservice/rest/server.php POST，带上 wstoken、wsfunction、moodlewsrestformat=json 和业务参数。前端页面内则可直接用 core/ajax 的 ajax.call([{methodname: ..., args: {...}}])。

步骤 7：出问题就查调试清单

检查 Moodle 调试模式、Web 服务日志、$CFG->dataroot/local_插件名/ 下的自定义日志文件、$DB->set_debug(true)、以及换成管理员账号排除权限因素。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
Moodle外部API开发Skill（本技能） 面向Moodle外部API的规范化代码生成助手 三方法模式、参数结构、安全校验、事务、服务注册、测试与排错全链路 需接入支持技能的AI宿主，另有Moodle开发环境；具体安装以官方说明为准 插件开发、课程管理接口、测验操作接口、移动端后端 优势：贴合官方规范、开箱即用、内置踩坑清单；不足：依赖宿主平台，非Moodle场景用不上
Moodle官方开发者文档 权威参考手册 API子系统说明、编码规范、数据库API文档 免费公开，但需自行检索与理解 需要查证细节、确认版本差异 优势：最权威；不足：不带生成能力，需要自己把文档翻译成代码
通用AI编程助手（代码补全型） 上下文补全 按现有文件续写代码 装IDE插件即可 日常编码提效 优势：融入编辑器、响应快；不足：不了解Moodle外部API的注册机制与返回结构约束，容易产出不符合规范的代码
手工开发 + 社区论坛检索 传统路径 全靠开发者经验 门槛最高 复杂定制需求 优势：完全可控；不足：参数结构、能力校验、缓存清理等细节需反复试错，迭代周期长

总体来看：官方文档解决"查得到"，通用补全解决"写得快"，而本技能解决的是"写得对且能上线"这一层。

该技能的典型应用场景与实际体验情况

场景一：高校LMS团队要开放课程数据给校本门户

角色：学校信息化中心的Moodle二次开发工程师。痛点是门户需要展示学生的课程完成情况，但直接读库风险高，走官方Web服务又不知道参数怎么定义。使用方式是让技能生成一个 read 类型接口，输入 userid 与 courseid，输出课程与时间戳列表，并在 execute() 中带上 moodle/course:view 能力校验。实际体验：骨架代码基本可直接落盘，只需按自己插件的表名替换 {your_table}；注意点是首次注册后务必清缓存。

场景二：培训机构要做"按标签随机组卷"的自动化测验

角色：教务系统开发者。痛点是每期开班都要批量创建测验并抽取指定标签的题目。技能给出的 get_random_questions() 方案通过 question_versions、question_bank_entries、tag_instance 联表取出候选题目 ID，shuffle 后 array_slice 截取，再配合 quiz_add_instance 与 course_add_cm_to_section 完成建课建活动。实际体验：写类型接口涉及多表插入，必须用 start_delegated_transaction() 包住，否则中途失败会留下脏数据；技能已把事务模板给出，照抄即可。

场景三：把活动限定给指定学员（基于组的可用性）

角色：企业培训平台运维。痛点是同一门课里不同学员只能看到分配给自己的活动。技能提供了"按 activity_{id}_user_{uid} 命名建组、加入 groups_members、再写入 course_modules.availability JSON 条件"的完整做法。实际体验：这段逻辑手工写极易漏掉 timeadded 或写错 JSON 结构，技能给的模板直接把 op、show、c、showc 结构摆出来，改造成本很低。

场景四：移动App后端对接Moodle

角色：App后端工程师。痛点是需要在 services.php 中挂到官方移动服务包里，让App直接调用。技能说明可在注册时使用 services => [MOODLE_OFFICIAL_MOBILE_SERVICE]，并提示 ajax 设为 true 以支持 AJAX/REST。实际体验：整体上手难度中等偏低，前提是理解Moodle的上下文与能力模型；对完全没接触过Moodle的新手，建议先跑通一个只读接口再扩展。

该技能能为用户带来的价值

  • 把规范成本前置：三方法模式、参数类型、安全校验这些"必须做但容易忘"的动作被固化进生成结果，减少"写完才发现不符合规范"的返工。
  • 显著压缩首次可用时间：从一个空白插件目录到第一个可被 curl 调通的接口，传统路径往往要在文档、缓存、权限之间来回排查多次；有了结构化模板与调试清单，试错次数明显下降。
  • 降低安全风险：参数化查询、validate_parameters()、require_capability() 作为默认动作出现，比"先跑通再补安全"更可靠。
  • 降低团队门槛：不熟悉Moodle内部机制的PHP开发者，也能按模板产出符合编码标准（小写、下划线命名）的代码，便于多人协作与代码评审。
  • 长期价值：产出的是一套可复用的模式库——事务模板、日志方法、随机抽题 SQL、可用性条件结构，后续新增接口可在此基础上快速扩展，插件能力沉淀为团队资产。

常见问题 FAQ

Q1：这个技能怎么安装？安装需要付费吗？

在支持 AI 技能的宿主平台中以技能ID 12178 或英文名 moodle-external-api-development 检索并添加即可。是否需要付费、是否有额度限制取决于所在平台的计费策略，具体价格与授权方式请以官方说明为准。技能本身是开发指导型内容，不依赖额外的云端服务。

Q2：它会不会直接帮我改服务器上的文件？

不会。该技能输出的是代码与操作步骤，落盘、清缓存、配置Web服务等动作需要你在自己的Moodle环境中执行。建议先在本地或测试站验证，再推到生产环境。

Q3：适合谁用？完全没写过Moodle插件能上手吗？

主要面向有PHP基础、需要为Moodle开发外部接口的开发者，以及负责LMS二开与集成的运维团队。如果你完全不熟悉Moodle，建议先理解"上下文（context）"与"能力（capability）"这两个概念，再照着技能里的只读接口示例走一遍，上手会顺很多。

Q4：和直接问通用AI有什么区别？

通用AI能写出语法正确的PHP，但不一定知道 methodname 必须是 execute、返回结构必须与 execute() 一致、改完 services.php 必须清缓存、写操作 type 不能填 read。该技能把这些Moodle特有的约束直接写进了生成逻辑，减少"代码能跑但接口调不通"的尴尬。

Q5：调用时报"函数未找到"或"检测到无效参数值"怎么办？

"函数未找到"优先清缓存（站点管理 > 开发 > 清除所有缓存），并核对 services.php 中的函数名与命名空间是否完全一致；"无效参数值"则检查参数类型在定义与调用间是否匹配、必填与可选是否设置正确、嵌套结构是否对齐。技能内还提供了调试模式、Web服务日志、自定义日志文件、$DB->set_debug(true) 等一整套排查路径。