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
 */