如何在MediaWiki中创建带自定义路由的自定义端点？

架构老林

2026-5-29

当然可以在MediaWiki里创建自定义端点！其实MediaWiki本身就提供了灵活的扩展机制来实现这类需求，不用局限于现有的REST API或者APISandbox。下面给你两种常用的实现思路，帮你搞定http://my.wikiexample.com/custom/deleteAccount这类自定义端点：

方法一：注册自定义REST端点（推荐，符合现代API规范）

这是最标准的方式，利用MediaWiki的REST路由扩展能力来实现：

创建基础扩展结构
先搭建一个MediaWiki扩展的骨架，核心是extension.json配置文件和对应的PHP逻辑文件，把它们放在MediaWiki的extensions/CustomEndpoints目录下。

在extension.json中注册路由
修改extension.json，添加REST路由的配置，指定端点路径、请求方法和处理类：

{
  "name": "CustomEndpoints",
  "version": "1.0",
  "author": ["Your Name"],
  "description": "Adds custom REST endpoints for account management",
  "license-name": "GPL-2.0-or-later",
  "requires": {
    "MediaWiki": ">=1.35"
  },
  "AutoloadClasses": {
    "CustomEndpoints\\Rest\\DeleteAccountHandler": "src/Rest/DeleteAccountHandler.php"
  },
  "RestRoutes": [
    {
      "path": "/custom/deleteAccount",
      "method": "POST",
      "handler": "CustomEndpoints\\Rest\\DeleteAccountHandler"
    }
  ]
}

编写端点处理逻辑
创建src/Rest/DeleteAccountHandler.php文件，实现具体的业务逻辑，比如权限验证、账号删除操作：

namespace CustomEndpoints\Rest;

use MediaWiki\Rest\Handler;
use MediaWiki\User\UserManager;
use MediaWiki\Permissions\PermissionManager;

class DeleteAccountHandler extends Handler {
    private $userManager;
    private $permissionManager;

    // 通过依赖注入获取MediaWiki核心服务
    public function __construct( UserManager $userManager, PermissionManager $permissionManager ) {
        $this->userManager = $userManager;
        $this->permissionManager = $permissionManager;
    }

    public function execute() {
        // 第一步：验证当前用户权限
        $currentUser = $this->getUser();
        if ( !$this->permissionManager->userHasRight( $currentUser, 'deleteaccount' ) ) {
            return $this->getResponseFactory()->createHttpError( 403, '无权限执行此操作' );
        }

        // 第二步：获取并校验请求参数
        $params = $this->getValidatedParams();
        $username = $params['username'] ?? '';
        if ( empty( $username ) ) {
            return $this->getResponseFactory()->createHttpError( 400, '必须提供用户名' );
        }

        // 第三步：执行账号删除逻辑
        $targetUser = $this->userManager->getUserByName( $username );
        if ( !$targetUser ) {
            return $this->getResponseFactory()->createHttpError( 404, '用户不存在' );
        }

        // 这里替换为实际的删除操作，比如调用MediaWiki的用户管理API
        // $this->userManager->removeUser( $targetUser );

        // 返回成功响应
        return $this->getResponseFactory()->createJson( [
            'status' => 'success',
            'message' => "账号 $username 已成功删除"
        ] );
    }

    // 定义请求参数规则
    public function getParamSettings() {
        return [
            'username' => [
                'type' => 'string',
                'required' => true
            ]
        ];
    }
}

启用扩展
在MediaWiki的LocalSettings.php末尾添加：
```
wfLoadExtension( 'CustomEndpoints' );
```
刷新MediaWiki缓存后，你的自定义端点就可以通过http://my.wikiexample.com/rest.php/custom/deleteAccount访问了（如果想去掉rest.php前缀，可以修改$wgRestPath配置）。

方法二：用特殊页面模拟端点（适合简单需求）

如果你的需求比较简单，也可以通过创建特殊页面来模拟端点：

编写特殊页面类
创建SpecialDeleteAccount.php文件，处理POST请求：

class SpecialDeleteAccount extends SpecialPage {
    public function __construct() {
        parent::__construct( 'DeleteAccount' );
    }

    public function execute( $par ) {
        $this->setHeaders();
        $request = $this->getRequest();
        $output = $this->getOutput();

        // 只允许POST请求
        if ( !$request->wasPosted() ) {
            $output->setStatusCode( 405 );
            $output->addHTML( '仅支持POST方法' );
            return;
        }

        // 权限验证
        $currentUser = $this->getUser();
        if ( !$currentUser->isAllowed( 'deleteaccount' ) ) {
            $output->setStatusCode( 403 );
            $output->addHTML( '无权限执行此操作' );
            return;
        }

        // 获取参数并执行删除逻辑
        $username = $request->getVal( 'username' );
        // ...这里添加删除账号的具体代码

        // 返回JSON响应
        $output->setContentType( 'application/json' );
        $output->addJSON( [ 'status' => 'success', 'message' => "账号 $username 删除成功" ] );
    }
}

注册特殊页面
在extension.json中添加特殊页面的配置，然后启用扩展，就可以通过http://my.wikiexample.com/index.php/Special:DeleteAccount作为端点，用POST请求传递参数。

一些重要注意事项

权限验证优先：一定要做好权限校验，避免未授权的用户执行敏感操作，这是安全的核心。
版本兼容性：不同MediaWiki版本的REST API细节可能有差异，建议参考你使用版本的官方开发者文档。
错误处理：完善的错误响应能让端点更易用，比如返回合适的HTTP状态码和清晰的错误信息。

内容的提问来源于stack exchange，提问作者user1292656

如何在MediaWiki中创建带自定义路由的自定义端点？

一些重要注意事项 #

一些重要注意事项