手册:Maxlag参数

maxlag is something that can be added to any Action API query. When set, the API query will ask the server if it is too busy. If it is, the API query will return an error instead of processing the API request. The error message will include the number of seconds behind it is, and this information can be used to determine how long to wait before retrying the query. The idea is to pause bot edits during times of high server load, to give human edits priority. This is an optional but recommended parameter, and many major bot frameworks such as pywikibot implement it by default.

如果您的MediaWiki是部署在並行式數據庫叢集中（如维基媒体所用），高频次的编辑可能使副本伺服器滞后。 其中一種解決辦法是，每當副本延誤超過某一臨界值时，自动停止所有機器人和維護工作。 MediaWiki 1.10中引進了maxlag參數，讓客戶端的程式可以處理這種情況。 自1.27版起，maxlag參數的機制仅限于api.php的請求。

使用api.php時，可以透過URL查詢字串或POST数据指明以秒為單位的整數作為maxlag參數。 例如，此链接显示"MediaWiki"页面的元数据，除非延时大于1秒，而此链接(在结尾加-1)显示了实际延迟而没有元数据。

如果请求时已超过指定的延迟，API将返回一个错误（状态码为200，参见工單T33156），内容如下：

{
    "error": {
        "code": "maxlag",
        "info": "Waiting for $host: $lag seconds lagged",
        "host": $host,
        "lag": $lag,
        "*": "See https://www.mediawiki.org/w/api.php for API usage"
    }
}

下列HTTP标头被设置：

• Retry-After: 建议客户端在重试前最少等待多少秒
• X-Database-Lag: 最滞后的数据库延滞秒数

对维基媒体项目的建议用法如下：

• 使用maxlag=5 (5秒)。这是个合适而不激进的值，已是Pywikibot的默认值。使用更高的值会有更激进（紧迫）的行为，而更低的值更友好（但请求成功率也降低）。

如果收到了一个延滞错误，将你的脚本暂停至少5秒后再试。当心不要因延滞进入死循环。

• 使用此值后，在数据库高负载时，您的请求可能成功执行率有所降低，此时只需等待非高峰期再做编辑。我们在高负载时应首先考虑人类的编辑，我们不想拒绝真人编辑而浪费他们的时间。
• 异常高或持久存在的延滞应当反馈至irc.freenode.net上的#wikimedia-tech ^連線。
• 交互式任务（用户正等待结果）可以省略maxlag参数。非交互式任务则应始终使用该参数。 另见API:Etiquette#The maxlag parameter。

注意，当上游服务器超时，缓存层（Varnish或squid）也可能生成503状态码的错误消息。 客户端应当区别对待这些错误，因为它们可能在你尝试运行一个长时间的费时操作时总是发生。 在超时后不断重复操作会占用过多服务器资源并使你的客户端陷入无限循环。 你可以使用下列任意方法区分缓存层错误与MediaWiki延滞条件：

• X-Database-Lag header头是MediaWiki复制延滞错误的特有特征
• Varnish错误中没有Retry-After标头
• X-Squid-Error标头应在squid错误中出现
• 复制延滞错误中的响应正文应与正则表达式 /Waiting for [^ ]*: [0-9.-]+ seconds? lagged//Waiting for [^ ]*: [0-9.-]+ seconds? lagged/ 匹配

出于测试目的，你可以设置一个负值故意让软件拒绝一个请求，例如下列URL：//www.mediawiki.org/w/api.php?action=query&titles=MediaWiki&format=json&maxlag=-1。