传统前端项目规范（JS + jQuery + HTML）

---

name: legacy-web-standard

description: 针对 JavaScript + jQuery + HTML/CSS 传统前端项目的开发与维护规范。当用户在非框架项目中工作，涉及 jQuery、原生 JS、传统多页面应用（MPA）、模板引擎渲染页面、或维护遗留代码时自动激活。

version: 1.0.0

---

# 传统前端项目规范（JS + jQuery + HTML）

适用于未使用现代框架（Vue / React / Angular）的传统前端项目，包括 jQuery 多页面应用、服务端模板渲染项目（JSP / Thymeleaf / PHP / Django Template / EJS / Handlebars 等）以及需要长期维护的遗留系统。

适用场景

核心原则

JavaScript 规范

基本要求

命名空间模式

var App = App || {};
App.UserModule = (function($) {
    'use strict';

    var config = {
        apiBase: '/api/v1'
    };

    function init() {
        bindEvents();
        loadData();
    }

    function bindEvents() {
        $(document).on('click', '.js-submit-btn', handleSubmit);
    }

    function handleSubmit(e) {
        e.preventDefault();
        // ...
    }

    return { init: init };
})(jQuery);

事件绑定

DOM 操作

Ajax 请求

function fetchUserList(params) {
    return $.ajax({
        url: config.apiBase + '/users',
        method: 'GET',
        data: params,
        dataType: 'json'
    }).done(function(res) {
        if (res.code === 0) {
            renderList(res.data);
        } else {
            showError(res.message);
        }
    }).fail(function(xhr) {
        showError('网络错误，请稍后重试');
    }).always(function() {
        hideLoading();
    });
}

jQuery 规范

选择器性能

插件使用

jQuery 反模式

避免：

HTML 规范

CSS 规范

安全要求

XSS 防护（重点）

传统项目是 XSS 的高发区，必须严格检查：

// 错误：XSS 风险
$('.username').html(userData.name);

// 正确：使用 .text() 转义
$('.username').text(userData.name);

// 正确：需要 HTML 时手动转义
function escapeHtml(str) {
    var div = document.createElement('div');
    div.appendChild(document.createTextNode(str));
    return div.innerHTML;
}
$('.comment').html('<p>' + escapeHtml(userData.comment) + '</p>');

其他安全项

文件组织

遵循项目已有约定。典型结构：

project/
├── css/
│   ├── common.css          # 全局样式
│   └── pages/
│       └── user-list.css   # 页面级样式
├── js/
│   ├── lib/                # 第三方库
│   │   ├── jquery.min.js
│   │   └── ...
│   ├── common/             # 公共模块
│   │   ├── utils.js
│   │   ├── ajax.js
│   │   └── constants.js
│   └── pages/              # 页面级脚本
│       └── user-list.js
├── images/
└── pages/                  # HTML 页面（如非模板引擎）

渐进改进建议

在维护遗留项目时，可以在不影响整体架构的前提下渐进引入：

但不要在一次改动中同时引入多项改进。每次聚焦一个点，确保不破坏现有功能。

输出检查清单