Moodle External API Development - Moodle 自定义 Web 服务开发完整指南

技能概述

这是一个专为 Moodle LMS 开发者设计的技能，提供创建自定义外部 Web Service API 的完整解决方案，涵盖从参数验证到服务注册的全流程最佳实践。

适用场景

1. 为 Moodle 插件开发自定义接口

当您需要为本地或课程模块插件创建对外 API 时，使用本技能可以快速构建符合 Moodle 标准的外部函数。支持创建用于课程管理、用户数据同步、成绩查询等各类业务场景的 REST 接口。

2. 开发移动应用后端

如果您正在基于 Moodle 构建移动应用，本技能提供了创建后端 API 的完整方案。包括用户认证、课程数据获取、测验提交、成绩查询等常用接口的实现方法，以及与 Moodle Mobile Service 的集成指南。

3. 实现第三方系统集成

当需要将 Moodle 与外部系统（如 HR 系统、ERP、数据分析平台）对接时，可以使用本技能创建安全的数据交换接口。涵盖参数验证、权限检查、SQL 防注入等安全最佳实践。

核心功能

1. 三方法架构模式实现

严格遵循 Moodle external API 框架要求，实现 execute_parameters()、execute()、execute_returns() 三个核心方法。提供完整的参数类型定义（PARAM_INT、PARAM_TEXT、PARAM_BOOL 等）和返回结构配置（external_value、external_single_structure、external_multiple_structure）示例。

2. 安全开发规范

内置完整的安全检查流程，包括参数验证（validate_parameters）、上下文验证（validate_context）、能力检查（require_capability）以及 SQL 注入防护。提供事务管理、错误日志记录和异常处理的最佳实践代码示例。

3. 服务注册与测试

详细说明 services.php 配置文件的编写方法，包括 classname、methodname、type、ajax、capabilities 等关键参数的设置。提供三种测试方式：Moodle Web Services 测试客户端、cURL 命令行、JavaScript AJAX 调用。

常见问题

如何在 Moodle 插件中创建自定义 web service？

创建 Moodle 自定义 web service 需要以下步骤：

1. 在插件的 classes/external/ 目录下创建 API 类文件，继承 external_api 基类
2. 实现三个必需方法：execute_parameters() 定义参数、execute() 实现业务逻辑、execute_returns() 定义返回值
3. 在 db/services.php 中注册服务，指定类名、方法名、权限要求等
4. 清除缓存后即可通过 REST 或 AJAX 调用

类文件必须使用正确的命名空间（如 local_yourplugin\external）并包含安全检查 defined('MOODLE_INTERNAL') || die()。

Moodle web service 报 "Function not found" 错误怎么解决？

"Function not found" 是最常见的错误，解决步骤如下：

1. 清除缓存：进入 网站管理 > 开发 > 清除所有缓存
2. 检查 services.php：确认函数名、类名、命名空间完全一致
3. 验证文件路径：classpath 指向的文件必须存在且可读
4. 检查命名空间：类文件的 namespace 必须与 services.php 中的 classname 匹配
5. 确认协议启用：在 网站管理 > 插件 > Web 服务 > 管理协议 中启用 REST 协议

如果问题持续，可以开启调试模式（网站管理 > 开发 > 调试）查看详细错误信息。

Moodle 外部 API 如何进行权限检查和防止 SQL 注入？

Moodle external API 的权限检查和安全防护：

权限检查流程：

// 1. 获取上下文
$context = \context_course::instance($courseid);
self::validate_context($context);

// 2. 检查能力
require_capability('moodle/course:view', $context);

// 3. 验证用户权限
if ($userid != $USER->id) {
    require_capability('moodle/course:viewhiddenactivities', $context);
}

防止 SQL 注入：

• 始终使用参数化查询，使用 :paramname 占位符
• 禁止字符串拼接用户输入到 SQL 语句
• 使用 Moodle 数据库 API：get_record()、get_records_sql()、insert_record() 等
• 必须通过 validate_parameters() 先验证所有输入参数

错误处理： 使用 try-catch 块捕获异常，记录详细日志（包括 SQL 查询和堆栈跟踪），然后重新抛出异常以便上层处理。