当前位置：首页 > news >正文

River插件开发入门：构建自定义请求修改器的完整指南

news 2026/3/26 22:38:46

River插件开发入门：构建自定义请求修改器的完整指南

【免费下载链接】river项目地址: https://gitcode.com/GitHub_Trending/river1/river

River是一个功能强大的代理框架，允许开发者通过插件扩展其功能。本文将带您逐步了解如何开发自定义请求修改器插件，轻松实现对HTTP请求的灵活处理。无论您是新手还是有经验的开发者，本指南都将帮助您快速掌握River插件开发的核心技能。

了解请求修改器的核心概念

请求修改器是River框架中处理HTTP请求的关键组件，位于source/river/src/proxy/request_modifiers.rs文件中。它们允许开发者在请求发送到上游服务器之前对其进行修改，例如添加、删除或修改请求头，重写URL路径等。

请求修改器的基本结构

每个请求修改器都需要实现RequestModifyModtrait，该trait定义了一个异步方法upstream_request_filter，用于处理请求：

#[async_trait] pub trait RequestModifyMod: Send + Sync { async fn upstream_request_filter( &self, session: &mut Session, header: &mut RequestHeader, ctx: &mut RiverContext, ) -> Result<()>; }

这个方法接收三个参数：会话对象、请求头和上下文，返回一个Result类型表示操作是否成功。

开发第一个请求修改器：添加自定义请求头

让我们从一个简单但实用的例子开始：创建一个能够添加自定义请求头的修改器。

步骤1：定义修改器结构体

首先，我们需要定义一个结构体来保存修改器的配置信息。对于添加请求头的修改器，我们需要存储要添加的头名称和值：

pub struct AddCustomHeader { key: String, value: String, }

步骤2：实现构造函数

接下来，实现一个从设置中创建修改器实例的方法。这个方法将从配置中提取必要的参数：

impl AddCustomHeader { pub fn from_settings(mut settings: BTreeMap<String, String>) -> Result<Self> { let key = extract_val("key", &mut settings)?; let value = extract_val("value", &mut settings)?; Ok(Self { key, value }) } }

步骤3：实现RequestModifyMod trait

现在，我们需要实现RequestModifyModtrait，重写upstream_request_filter方法来添加请求头：

#[async_trait] impl RequestModifyMod for AddCustomHeader { async fn upstream_request_filter( &self, _session: &mut Session, header: &mut RequestHeader, _ctx: &mut RiverContext, ) -> Result<()> { header.append_header(self.key.clone(), &self.value)?; tracing::debug!("Added custom header: {}: {}", self.key, self.value); Ok(()) } }

高级修改器：基于正则表达式删除请求头

River框架已经提供了一些内置的请求修改器，例如RemoveHeaderKeyRegex。让我们看看它是如何实现的，以便我们了解更复杂的修改器开发。

RemoveHeaderKeyRegex实现分析

RemoveHeaderKeyRegex修改器允许根据正则表达式匹配来删除请求头：

pub struct RemoveHeaderKeyRegex { regex: Regex, } impl RemoveHeaderKeyRegex { pub fn from_settings(mut settings: BTreeMap<String, String>) -> Result<Self> { let mat = extract_val("pattern", &mut settings)?; let reg = Regex::new(&mat).map_err(|e| { tracing::error!("Bad pattern: '{mat}': {e:?}"); Error::new_str("Error building regex") })?; ensure_empty(&settings)?; Ok(Self { regex: reg }) } } #[async_trait] impl RequestModifyMod for RemoveHeaderKeyRegex { async fn upstream_request_filter( &self, _session: &mut Session, header: &mut RequestHeader, _ctx: &mut RiverContext, ) -> Result<()> { let headers = header .headers .keys() .filter_map(|k| { if self.regex.is_match(k.as_str()) { tracing::debug!("Removing header: {k:?}"); Some(k.to_owned()) } else { None } }) .collect::<Vec<_>>(); for h in headers { assert!(header.remove_header(&h).is_some()); } Ok(()) } }

这个实现展示了如何使用正则表达式进行模式匹配，以及如何安全地修改请求头。

在配置文件中使用自定义修改器

开发完成后，您需要在配置文件中注册和配置自定义修改器。虽然TOML配置可能会被弃用，但目前您可以在basic-proxy.path-control.upstream-request-filters部分添加您的修改器：

[basic-proxy.path-control] upstream-request-filters = [ { kind = "AddCustomHeader", key = "X-Custom-Header", value = "custom-value" }, { kind = "RemoveHeaderKeyRegex", pattern = "X-.*-Header" } ]