MySQL注释的三种写法之单行注释、多行注释和特殊注释的使用方法

-- 这是单行注释
SELECT * FROM users; -- 这是语句后的注释

-- 用户基本信息查询
-- 创建时间：2023-05-20
-- 创建者：DBA团队
SELECT 
    user_id, -- 用户唯一标识
    username, -- 登录用户名
    email -- 注册邮箱
FROM 
    users
WHERE 
    status = 1; -- 1表示活跃用户

-- 第一行注释
-- 第二行注释

INSERT INTO logs (message) VALUES ('--这不是注释');

# 这是井号注释
SELECT * FROM products # 这也是井号注释

# 产品库存报表
# 版本：1.2
# 最后更新：2023-06-15
SELECT 
    p.product_id,    # 产品ID
    p.product_name,  # 产品名称
    s.quantity       # 当前库存量
FROM 
    products p
JOIN 
    stock s # 库存表
    ON p.product_id = s.product_id
WHERE 
    p.discontinued = 0; # 0表示在售产品

SELECT 
    user_id,
    username,
    -- email,
    phone_number
FROM 
    users
WHERE 
    -- status = 1 AND 
    registration_date > '2023-01-01';

-- 不安全写法(拼接SQL)
SET @sql = CONCAT('SELECT * FROM users WHERE username="', @input, '"');
PREPARE stmt FROM @sql;
EXECUTE stmt;
-- 安全写法(参数化查询)
PREPARE stmt FROM 'SELECT * FROM users WHERE username=?';
EXECUTE stmt USING @input;

-- @api {get} /users 获取用户列表
-- @apiGroup User
-- @apiParam {Number} [page=1] 页码
-- @apiParam {Number} [limit=20] 每页数量
SELECT * FROM users LIMIT :limit OFFSET (:page - 1) * :limit;

/* 这是一个
多行注释 */
SELECT * FROM employees;

/*
 * 员工薪资统计报表
 * 功能：计算各部门薪资分布
 * 包含：基本工资、奖金、补贴
 * 排除：已离职员工
 * 作者：HR系统团队
 * 版本：2.1
 */
SELECT 
    department_id,
    AVG(salary) AS avg_salary
FROM 
    employees
WHERE 
    status = 'active'
GROUP BY 
    department_id;

SELECT product_name FROM products;
/*
SELECT product_name 
FROM products 
WHERE discontinued = 0
ORDER BY create_time DESC;
*/

SELECT 
    /* 获取客户基本信息 */
    c.customer_id,
    c.customer_name,
    /* 计算订单总额 */
    SUM(o.amount) AS total_amount
FROM 
    customers c
    /* 关联订单表 */
    LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY 
    c.customer_id, c.customer_name;

/*
 * 第一行注释
 * 第二行注释
 * 第三行注释
 */

/*=============================================
 * 模块名称：用户权限管理
 * 主要功能：查询用户权限列表
 * 调用关系：
 *   - 依赖roles表
 *   - 被admin模块调用
 =============================================*/

/* 单行注释也可以使用多行语法 */

/* 外层注释
   /* 内层注释 */
   这部分会被当作SQL语句执行 */

/* 外层注释 */
/*! 内层"注释"实际上是可以执行的代码 */
/* 外层注释继续 */

/* 外层注释开始
-- 内层"注释"使用单行形式
外层注释继续 */

/*!50100 这部分在MySQL 5.1.00+会执行
/* 这看起来像嵌套但不是真正的嵌套 */
*/

DELIMITER //
/*====================================
 * 存储过程：update_customer_status
 * 功能：批量更新客户状态
 * 参数：
 *   - p_customer_ids: 客户ID列表(逗号分隔)
 *   - p_new_status: 新状态值
 * 返回值：受影响的行数
 * 创建日期：2023-03-15
 * 修改历史：
 *   2023-04-01 增加事务处理
 ====================================*/
CREATE PROCEDURE update_customer_status(
    IN p_customer_ids TEXT,
    IN p_new_status INT,
    OUT p_affected_rows INT
)
BEGIN
    /* 声明变量 */
    DECLARE v_start_time DATETIME DEFAULT NOW();
    /* 记录操作日志 */
    INSERT INTO procedure_logs (proc_name, start_time)
    VALUES ('update_customer_status', v_start_time);
    /* 主处理逻辑 */
    SET @sql = CONCAT('UPDATE customers SET status = ', 
                     p_new_status, 
                     ' WHERE customer_id IN (', 
                     p_customer_ids, ')');
    PREPARE stmt FROM @sql;
    EXECUTE stmt;
    SET p_affected_rows = ROW_COUNT();
    DEALLOCATE PREPARE stmt;
    /* 更新日志 */
    UPDATE procedure_logs 
    SET end_time = NOW(),
        affected_rows = p_affected_rows
    WHERE proc_name = 'update_customer_status'
    AND start_time = v_start_time;
END //
DELIMITER ;

DELIMITER //
/*
 * 函数名称：calculate_discount
 * 功能：基于订单金额计算折扣率
 * 参数：
 *   - p_order_amount: 订单金额(DECIMAL)
 * 返回值：折扣率(DECIMAL)
 * 业务规则：
 *   - 金额<100: 无折扣
 *   - 100≤金额<500: 5%折扣
 *   - 500≤金额<1000: 8%折扣
 *   - 金额≥1000: 10%折扣
 */
CREATE FUNCTION calculate_discount(p_order_amount DECIMAL(10,2))
RETURNS DECIMAL(3,2)
DETERMINISTIC
BEGIN
    DECLARE v_discount DECIMAL(3,2) DEFAULT 0.00;
    /* 应用折扣规则 */
    IF p_order_amount >= 100 AND p_order_amount < 500 THEN
        SET v_discount = 0.05;
    ELSEIF p_order_amount >= 500 AND p_order_amount < 1000 THEN
        SET v_discount = 0.08;
    ELSEIF p_order_amount >= 1000 THEN
        SET v_discount = 0.10;
    END IF;
    RETURN v_discount;
END //
DELIMITER ;

DELIMITER //
/*====================================
 * 触发器：tri_after_order_insert
 * 表：orders
 * 时机：AFTER INSERT
 * 功能：订单创建后更新客户最后购买时间
 * 逻辑：
 *   - 获取新订单的客户ID
 *   - 更新customers表的last_purchase字段
 ====================================*/
CREATE TRIGGER tri_after_order_insert
AFTER INSERT ON orders
FOR EACH ROW
BEGIN
    /* 更新客户最后购买时间 */
    UPDATE customers 
    SET last_purchase = NOW()
    WHERE customer_id = NEW.customer_id;
    /* 记录触发器执行日志 */
    INSERT INTO trigger_logs 
    (trigger_name, affected_table, execution_time)
    VALUES 
    ('tri_after_order_insert', 'orders', NOW());
END //
DELIMITER ;

/*! SELECT 1+1; */

CREATE TABLE example (
    id INT PRIMARY KEY,
    data JSON /*!50706 COMMENT 'JSON类型要求MySQL 5.7.6+' */
);

CREATE TABLE products (
    id INT PRIMARY KEY,
    /*!50706 details JSON, */
    /*!50706 full_text TEXT GENERATED ALWAYS AS (details->>"$.description") STORED, */
    price DECIMAL(10,2)
);

SELECT 
    employee_id,
    department_id,
    salary,
    /*!80021 RANK() OVER (PARTITION BY department_id ORDER BY salary DESC) AS dept_rank */
FROM 
    employees;

CREATE USER 'newuser'@'localhost' 
IDENTIFIED /*!50706 WITH caching_sha2_password */ BY 'password';

/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
/*!40101 SET NAMES utf8mb4 */;
/*!40103 SET @OLD_TIME_ZONE=@@TIME_ZONE */;
/*!40103 SET TIME_ZONE='+00:00' */;
/*!40014 SET @OLD_UNIQUE_CHECKS=@@UNIQUE_CHECKS, UNIQUE_CHECKS=0 */;
/*!40014 SET @OLD_FOREIGN_KEY_CHECKS=@@FOREIGN_KEY_CHECKS, FOREIGN_KEY_CHECKS=0 */;
/*!40101 SET @OLD_SQL_MODE=@@SQL_MODE, SQL_MODE='NO_AUTO_VALUE_ON_ZERO' */;
/*!40111 SET @OLD_SQL_NOTES=@@SQL_NOTES, SQL_NOTES=0 */;
-- 实际迁移SQL...
/*!40103 SET TIME_ZONE=@OLD_TIME_ZONE */;
/*!40101 SET SQL_MODE=@OLD_SQL_MODE */;
/*!40014 SET FOREIGN_KEY_CHECKS=@OLD_FOREIGN_KEY_CHECKS */;
/*!40014 SET UNIQUE_CHECKS=@OLD_UNIQUE_CHECKS */;
/*!40101 SET CHARACTER_SET_CLIENT=@OLD_CHARACTER_SET_CLIENT */;
/*!40101 SET CHARACTER_SET_RESULTS=@OLD_CHARACTER_SET_RESULTS */;
/*!40101 SET COLLATION_CONNECTION=@OLD_COLLATION_CONNECTION */;
/*!40111 SET SQL_NOTES=@OLD_SQL_NOTES */;

CREATE TABLE example (
    id INT PRIMARY KEY
) /*!50100 ENGINE = InnoDB */;

CREATE TABLE multilingual (
    id INT PRIMARY KEY,
    content VARCHAR(100) /*!50500 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci */
);

SELECT /*+ MAX_EXECUTION_TIME(1000) */ * FROM large_table;

/*+ MAX_EXECUTION_TIME(500) */

/*+ INDEX(table idx_name) */

/*+ JOIN_ORDER(t1, t2, t3) */

/*+ SEMIJOIN(FIRSTMATCH) */

/* 复杂查询优化示例 */
SELECT 
    /*+ 
        MAX_EXECUTION_TIME(1000)
        BKA(c)
        NO_RANGE_OPTIMIZATION(o)
    */
    c.customer_name,
    o.order_date,
    o.amount
FROM 
    customers c
    JOIN orders o /*+ JOIN_ORDER(c, o) */ 
        ON c.customer_id = o.customer_id
WHERE 
    o.order_date > '2023-01-01'
ORDER BY 
    o.amount DESC;

CREATE TABLE employees (
    emp_id INT PRIMARY KEY COMMENT '员工唯一标识，自动递增',
    emp_name VARCHAR(50) NOT NULL COMMENT '员工姓名，最多50个字符',
    salary DECIMAL(10,2) COMMENT '月薪，包含基本工资和岗位工资',
    hire_date DATE COMMENT '入职日期，YYYY-MM-DD格式'
) COMMENT='公司员工基本信息表';

/*
 * 查询名称：monthly_sales_report
 * 功能：生成分地区月度销售报表
 * 业务逻辑：
 *   - 只统计已完成的订单(status=3)
 *   - 排除测试账号(user_type=9)
 *   - 按地区和月份分组汇总
 * 性能说明：
 *   - 使用idx_region_time复合索引
 *   - 结果集预计100-200行
 * 修改历史：
 *   2023-01-15 增加退货金额计算
 *   2023-03-22 优化地区关联方式
 */
SELECT 
    r.region_name,
    DATE_FORMAT(o.order_time, '%Y-%m') AS month,
    SUM(o.amount) AS total_sales,
    COUNT(DISTINCT o.customer_id) AS customer_count
FROM 
    orders o
    JOIN regions r ON o.region_id = r.region_id
WHERE 
    o.status = 3
    AND o.user_type != 9
GROUP BY 
    r.region_name, 
    DATE_FORMAT(o.order_time, '%Y-%m');

/* 
 * 执行计划说明：
 *   - 使用idx_composite覆盖索引避免回表
 *   - 范围扫描约500行
 *   - 临时表排序预计需要1MB内存
 */
EXPLAIN 
SELECT product_id, product_name 
FROM products 
WHERE category_id = 5 
AND price BETWEEN 100 AND 500
ORDER BY create_time DESC;

-- 强制使用特定索引(适用于优化器选择不佳时)
SELECT * FROM orders FORCE INDEX(idx_order_date) 
WHERE order_date BETWEEN '2023-01-01' AND '2023-01-31';
-- 忽略特定索引(适用于索引过多干扰优化器)
SELECT * FROM orders IGNORE INDEX(idx_customer_id)
WHERE customer_id = 100 AND status = 1;

/*
 * 原始查询：使用子查询方式，执行时间约2.3秒
 * SELECT * FROM products WHERE category_id IN 
 * (SELECT category_id FROM categories WHERE department = 'electronics')
 * 
 * 优化后：使用JOIN改写，执行时间约0.8秒
 * 优化思路：避免DEPENDENT SUBQUERY
 */
SELECT p.* 
FROM products p
JOIN categories c ON p.category_id = c.category_id
WHERE c.department = 'electronics';

-- 使用mysqldoc格式的注释
-- @table products 产品信息表
-- @description 存储公司所有产品的基本信息
-- @author DBA Team
-- @field product_id 产品ID，主键
-- @field product_name 产品名称，唯一
-- @field price 零售价格，单位元
CREATE TABLE products (
    product_id INT PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE,
    price DECIMAL(10,2)
);

/*
 * $Id$
 * $HeadURL$
 * $LastChangedRevision$
 * $LastChangedBy$
 * $LastChangedDate$
 */
CREATE TABLE inventory (
    item_id INT PRIMARY KEY,
    quantity INT NOT NULL DEFAULT 0
);

-- 包含特殊字符的注释
SELECT * FROM translations 
WHERE text LIKE '%注释%'; -- 这里的"注释"是中文
/* 
 * 多语言注释示例
 * 日本語のコメント
 * русский комментарий
 * 中文注释
 */

-- 显式设置客户端字符集
SET character_set_client = utf8mb4;
SET character_set_connection = utf8mb4;
SET character_set_results = utf8mb4;
/* 现在可以安全使用多语言注释 */

[mysqld]
replicate-wild-ignore-table=%.comments_table

-- 不安全：注释可能被注入闭合
SELECT * FROM users WHERE id = 1 /* AND admin = 1 */;
-- 安全：使用参数化查询
PREPARE stmt FROM 'SELECT * FROM users WHERE id = ?';
EXECUTE stmt USING @user_id;

-- 测试查询(不带注释)
SELECT BENCHMARK(1000000, (SELECT 1 FROM dual));
-- 测试查询(带大量注释)
SELECT /* 大量注释... */ BENCHMARK(1000000, 
(SELECT /* 子查询注释 */ 1 FROM dual /* dual表注释 */));

SELECT 
    user_id,
    username,
    /* DEBUG: email, */
    phone_number
FROM 
    users
WHERE 
    status = 1
    /* AND account_type = 'premium' */

/* 查询开始时间：2023-07-20 14:30:00 */
SELECT * FROM large_table;
/* 查询结束时间：2023-07-20 14:30:05 */

/* 开启性能分析 */
SET profiling = 1;
-- 执行待分析查询
SELECT * FROM orders WHERE order_date > '2023-01-01';
/* 查看分析结果 */
SHOW PROFILE;

/* 动态SQL生成示例 */
SET @table_name = 'employees';
SET @sql = CONCAT('SELECT * FROM ', @table_name, ' /* 来源表：', @table_name, ' */');
PREPARE stmt FROM @sql;
EXECUTE stmt;

CREATE PROCEDURE debug_procedure()
BEGIN
    DECLARE v_debug BOOL DEFAULT TRUE;
    /* 调试输出 */
    IF v_debug THEN
        SELECT 'Procedure started' AS debug_log;
    END IF;
    -- 主逻辑...
    /* 调试输出 */
    IF v_debug THEN
        SELECT CONCAT('Rows affected: ', ROW_COUNT()) AS debug_log;
    END IF;
END;

/*
 * 变更记录：
 * 2023-01-10 v1.0 初始创建
 * 2023-02-15 v1.1 增加status字段索引
 * 2023-03-20 v1.2 调整price字段精度
 */
ALTER TABLE products
ADD INDEX idx_status (status),
MODIFY COLUMN price DECIMAL(12,2);

-- git-blame: 了解每行修改历史
-- git-log: 查看完整变更记录
/*
 * 最后修改人：john.doe@example.com
 * 最后修改时间：2023-05-15 14:30
 * 提交哈希：a1b2c3d4
 */