JSP 注释方式完整指南

原创已于 2025-12-18 14:06:21 修改 · 537 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#java #servlet #开发语言 #jsp #代码规范

于 2025-12-18 10:54:23 首次发布

写文档前的BB，只有BB才能让我后续梳理的快乐一点。

JSP虽然已经不流行了，但是还是会有很多不经常用、没必要大改的功能还遗留在那里，平时只需要简单维护一下，不需要做什么修改，而我很“幸运”竟然要干这个活唉~~~

示例文件：comments_example.jsp

一、JSP注释类型概览

1. JSP注释（服务器端注释）

<%-- 这是JSP注释，不会发送到客户端 --%>

特点：

仅在服务器端可见
不会发送到客户端浏览器
可以包含JSP代码和表达式

2. HTML/XML注释（客户端注释）

<!-- 这是HTML注释，会发送到客户端 -->

特点：

会发送到客户端浏览器
在浏览器查看源代码时可见
不能包含动态内容

3. Java代码注释

<%
    // 单行Java注释
    /*
        多行Java注释
        可以跨多行
    */
    /** Java文档注释 */
%>

特点：

仅在Scriptlet标签内有效
遵循Java注释语法
服务器端处理

二、详细示例

示例文件：`comments_example.jsp`

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ page import="java.util.Date" %>
<!DOCTYPE html>
<html>
<head>
    <title>JSP注释示例</title>
</head>
<body>
    <%-- ============================ --%>
    <%-- JSP注释示例区域（服务器端） --%>
    <%-- ============================ --%>
    
    <!-- ============================ -->
    <!-- HTML注释示例区域（客户端）  -->
    <!-- ============================ -->
    
    <h1>JSP各种注释方式演示</h1>
    
    <%-- 1. 在指令中使用JSP注释 --%>
    <%@ page import="java.util.*" %>
    <%-- 这是一个页面指令注释 --%>
    
    <%-- 2. 在声明中使用注释 --%>
    <%!
        // Java单行注释
        private String name = "示例";
        
        /*
            Java多行注释
            在声明标签中
        */
        
        /**
         * Java文档注释
         * @return 返回名称
         */
        public String getName() {
            return name;
        }
    %>
    
    <%-- 3. 在Scriptlet中使用注释 --%>
    <%
        // 获取当前时间
        Date now = new Date();
        
        /*
            多行注释示例：
            1. 注释1
            2. 注释2
        */
        
        // 输出变量值
        out.println("当前时间：" + now);
    %>
    
    <%-- 4. 在表达式中的注释 --%>
    <p>服务器时间：<%= /* 内联注释 */ new Date() %></p>
    
    <!-- 5. 在HTML标签中的HTML注释 -->
    <div>
        <!-- 这个div显示动态内容 -->
        <p>用户名：<%= request.getParameter("user") %></p>
    </div>
    
    <%-- 6. 条件注释示例 --%>
    <%
        boolean debugMode = true;
        if (debugMode) {
    %>
        <%-- 调试信息（生产环境不会显示） --%>
        <div style="background: yellow; padding: 10px;">
            调试模式已启用
        </div>
    <%
        }
    %>
    
    <!-- 7. 包含HTML注释的JSP代码 -->
    <!-- 
        这段代码会在客户端显示：
        当前用户：<%-- 这里不会显示 --%>
    -->
    
    <%-- 8. 禁用代码块的注释 --%>
    <%--
    <%
        // 这段代码被注释掉了
        String test = "不会执行";
        out.println(test);
    %>
    --%>
    
    <!-- 9. 模板文本中的注释 -->
    <script type="text/javascript">
        // JavaScript注释
        /* 
            JavaScript多行注释
        */
        function test() {
            var x = <%= 10 + 20 %>; // JSP表达式在JS中
        }
    </script>
    
    <style>
        /* CSS注释 */
        body {
            margin: 0; /* 内联CSS注释 */
        }
    </style>
</body>
</html>

三、注释使用场景对比

注释类型	语法	可见位置	用途	示例
JSP注释	`<%-- --%>`	仅服务器端	注释JSP代码、调试、临时禁用代码	`<%-- 临时禁用 --%>`
HTML注释	`<!-- -->`	客户端浏览器	注释HTML内容、给前端开发者看	`<!-- 导航菜单 -->`
Java单行	`//`	仅服务器端	注释单行Java代码	`// 初始化变量`
Java多行	`/* */`	仅服务器端	注释多行Java代码	`/* 算法实现 */`
Java文档	`/** */`	服务器端	生成API文档	`/** 获取用户 */`

四、最佳实践

1. 安全性考虑

<%-- 安全：包含敏感信息的注释 --%>
<%-- 数据库密码：xyz123 --%>

<!-- 不安全：会泄露到客户端 -->
<!-- 管理员账号：admin -->

2. 调试技巧

<%-- 调试输出开始 --%>
<%
    System.out.println("=== 调试信息 ===");
    System.out.println("参数列表：" + request.getParameterMap());
    // 临时调试代码
    // response.sendRedirect("error.jsp");
%>
<%-- 调试输出结束 --%>

3. 代码组织

<%-- ======================= --%>
<%-- 用户管理模块            --%>
<%-- 创建时间：2024-01-20    --%>
<%-- 修改记录：              --%>
<%-- 1. 添加分页功能         --%>
<%-- ======================= --%>

4. 条件注释

<%-- 根据环境显示不同内容 --%>
<%
    String env = System.getProperty("env");
    if ("dev".equals(env)) {
%>
    <%-- 开发环境专用代码 --%>
    <script src="debug_tool.js"></script>
<%
    }
%>

五、常见问题

1. 嵌套注释问题

<%-- 正确：单层注释 --%>

<%-- 错误：不能嵌套JSP注释
<%-- 内层注释 --%>
--%>

<!-- HTML注释可以嵌套JSP注释 -->
<!-- 
    外部HTML注释
    <%-- 内部JSP注释 --%>
    继续HTML注释
-->

<%--
 内层注释 
//这是另一个注释
--%>

2. 动态内容注释

<%-- 错误：JSP注释中的表达式不会执行 --%>
<%-- 当前用户：<%= user.getName() %> --%>

<!-- 正确：HTML注释中的表达式会执行 -->
<!-- 当前用户：<%= user.getName() %> -->

3. 性能考虑

<%-- 大量JSP注释会增加解析时间 --%>

<%
    // 过多的Java注释影响可读性
    // 保持注释简洁明了
%>

总结

核心原则：“谁的代码，用谁的注释”

这是保证安全稳妥的黄金法则。在JSP页面中，浏览器和Tomcat服务器会各自解析自己负责的部分，互不干扰。因此，你必须“对谁说话，就用谁的语言”：

对 浏览器 的 JavaScript 引擎说话 → 用 // 或 /* */
对 Tomcat 的 JSP 引擎说话 → 用 <%-- --%>

三种典型场景的稳妥写法示例

场景1：注释纯JavaScript逻辑（最安全）

<script>
// 单行注释：这是一个调试函数
function debugLog(msg) {
    /* 
        多行注释：
        这里可以写详细的函数说明，
        或者临时禁用一大段JS代码。
     */
    console.log("[DEBUG] " + msg);
}
</script>

✅ 效果：注释只在浏览器端生效，服务器原样输出，绝对安全。

场景2：注释含JSP标签的JavaScript（必须用JSP注释）

<script>
var apiUrl = '<%= getDynamicApiUrl() %>'; // 这行JSP表达式**会执行**
 
<%-- 稳妥：整个JSP表达式被服务器端移除 --%>
<%-- var secretToken = '<%= user.getToken() %>'; --%> 
 
// 危险！看似注释了，但JSP仍会执行并暴露Token！
// var secretToken = '<%= user.getToken() %>'; 
</script>

⚠️ 关键：只要涉及 <%、<%=、<c:if>、<shiro: 等，就必须用 <%-- --%>，否则会产生安全漏洞。

场景3：注释整个混合的`<script>`块（最稳妥）

当代码块混合了JS和JSP时，从最外层用JSP注释包裹是最彻底、最安全的方法。

<%-- 稳妥：整段脚本块被服务器端移除，绝对安全 --%>
<%--
<script>
    // 这里有JS代码
    var x = 1;
    // 这里混有JSP代码
    var y = '<%= someSecretValue %>'; // 这行不会暴露
    <c:if test="${condition}"> // 这个标签不会执行
        console.log('condition met');
    </c:if>
</script>
--%>

💡 替代方案：如果需要保留代码结构便于将来恢复，可以使用之前讨论过的 <% if(false){ %>包裹法。