MySQL - 注释

MySQL: 在 SQL 中使用注释

目录

- 注释在 SQL 中的作用
- 单行注释
- 多行注释
- 放置注释的最佳实践
- 在客户端程序中使用注释

注释在 SQL 中的作用

注释是 SQL 代码中用于文档化和解释其逻辑的不可执行文本。数据库引擎会完全忽略它们。它们对于可维护性至关重要，有助于其他开发人员（以及未来的您自己）理解复杂查询、存储过程或特定代码行的目的。

MySQL 支持三种注释风格。

单行注释

单行注释用于简短说明。它们以两个连字符（-- ）或一个井号（#）开头，并持续到行尾。注意：-- 风格需要在两个连字符后有一个空格才符合标准 SQL，尽管 MySQL 通常比较宽松。

示例

-- 从 customers 表中获取所有活跃用户。
SELECT *
FROM customers
WHERE is_active = 1; # 我们只想要当前活跃的客户

-- 以下查询暂时禁用，用于测试。
-- SELECT * FROM old_customers;

多行注释

多行注释，也称为块注释，用于较长的解释或注释掉一段代码。它们以 /* 开头，以 */ 结尾。这些标记之间的所有内容都会被忽略。

示例

这里，多行注释用于解释一个更复杂的查询，并暂时注释掉 SELECT 子句的一部分。

/*
  此查询计算每个客户在上一季度的总订单价值。
  它连接了 customers 和 orders 表。
  - 作者：J. Doe
  - 最后修改：2023-10-27
*/
SELECT
    c.customer_name,
    /* c.customer_email, -- 暂时移除，用于隐私审查 */
    SUM(o.order_value) AS total_spent
FROM
    customers c
JOIN
    orders o ON c.customer_id = o.customer_id
WHERE
    o.order_date >= CURDATE() - INTERVAL 3 MONTH
GROUP BY
    c.customer_id, c.customer_name;

放置注释的最佳实践

您可以在 SQL 代码中的几乎任何位置放置注释。有效的注释侧重于“为什么”，而不是“是什么”。

• 在脚本或存储过程的顶部： 使用块注释描述其整体目的、作者和修订历史。
• 在复杂语句之前： 解释复杂查询的业务逻辑或目标。
• 内联注释以澄清特定部分： 使用单行注释解释一个棘手的 WHERE 条件或一个不明显的计算。

/*
  存储过程：GetHighValueCustomers
  目的：查找所有生命周期价值超过指定阈值的客户。
*/
DELIMITER //
CREATE PROCEDURE GetHighValueCustomers(IN threshold DECIMAL(10, 2))
BEGIN
    -- 子查询计算每个客户的生命周期价值。
    SELECT customer_id, total_spent
    FROM (
        SELECT customer_id, SUM(order_value) as total_spent
        FROM orders
        GROUP BY customer_id
    ) AS customer_totals
    WHERE total_spent > threshold; -- 根据输入阈值进行过滤。
END //
DELIMITER ;

在客户端程序中使用注释

由于注释是 SQL 字符串的一部分，您可以在从任何编程语言执行查询时包含它们。这对于调试特别有用，因为您可以在数据库日志中看到带文档的查询。

示例：动态注释列

在此示例中，我们构建一个查询，该查询根据应用程序逻辑有条件地包含或注释掉某些列。

Python
Node.js
PHP
Java



**设置：** `pip install mysql-connector-python`

```python
import mysql.connector

# --- 配置 ---
db_config = { 'host': 'localhost', 'user': 'root', 'password': 'password', 'database': 'TUTORIALS' }

# --- 逻辑 ---
include_sensitive_data = False

sensitive_cols = "c.email, c.phone" if include_sensitive_data else "/* c.email, c.phone -- 已排除 */"

query = f"""
    -- 获取客户数据
    SELECT
        c.id,
        c.name,
        {sensitive_cols}
    FROM
        CUSTOMERS c
    WHERE
        c.city = %s;
"""

try:
    with mysql.connector.connect(**db_config) as conn:
        with conn.cursor(dictionary=True) as cursor:
            cursor.execute(query, ('Mumbai',))
            results = cursor.fetchall()
            print("Query executed successfully. Records found:")
            for row in results:
                print(row)
except mysql.connector.Error as e:
    print(f"Error: {e}")

设置： npm install mysql2

const mysql = require('mysql2/promise');

// --- 配置 ---
const dbConfig = { host: 'localhost', user: 'root', password: 'password', database: 'TUTORIALS' };

// --- 逻辑 ---
const includeSensitiveData = false;

const sensitiveCols = includeSensitiveData ? "c.email, c.phone" : "/* c.email, c.phone -- 已排除 */";

const query = `
    -- 获取客户数据
    SELECT
        c.id,
        c.name,
        ${sensitiveCols}
    FROM
        CUSTOMERS c
    WHERE
        c.city = ?;`;

async function runQuery() {
    let connection;
    try {
        connection = await mysql.createConnection(dbConfig);
        const [rows] = await connection.execute(query, ['Mumbai']);
        console.log('Query executed successfully. Records found:');
        console.log(rows);
    } catch (error) {
        console.error(`Error: ${error.message}`);
    } finally {
        if (connection) await connection.end();
    }
}

runQuery();

设置： 使用 Composer 管理依赖。

<?php
// --- 配置 ---
$dbConfig = ['host' => 'localhost', 'user' => 'root', 'password' => 'password', 'database' => 'TUTORIALS'];

// --- 逻辑 ---
$includeSensitiveData = false;

$sensitiveCols = $includeSensitiveData ? "c.email, c.phone" : "/* c.email, c.phone -- 已排除 */";

$query = "
    -- 获取客户数据
    SELECT
        c.id,
        c.name,
        {$sensitiveCols}
    FROM
        CUSTOMERS c
    WHERE
        c.city = ?;";

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
try {
    $mysqli = new mysqli($dbConfig['host'], $dbConfig['user'], $dbConfig['password'], $dbConfig['database']);
    $stmt = $mysqli->prepare($query);
    $city = 'Mumbai';
    $stmt->bind_param('s', $city);
    $stmt->execute();
    $result = $stmt->get_result();

    echo "Query executed successfully. Records found:\n";
    while ($row = $result->fetch_assoc()) {
        print_r($row);
    }
} catch (mysqli_sql_exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

?>

设置： 将 MySQL JDBC 驱动程序添加到您的项目（例如，通过 Maven）。

import java.sql.*;

public class CommentsInQuery {
    public static void main(String[] args) {
        // --- 配置 ---
        String url = "jdbc:mysql://localhost:3306/TUTORIALS";
        String user = "root";
        String password = "password";

        // --- 逻辑 ---
        boolean includeSensitiveData = false;

        String sensitiveCols = includeSensitiveData ? "c.email, c.phone" : "/* c.email, c.phone -- 已排除 */";

        String query = String.format("""
            -- 获取客户数据
            SELECT
                c.id,
                c.name,
                %s
            FROM
                CUSTOMERS c
            WHERE
                c.city = ?;""", sensitiveCols);

        try (Connection conn = DriverManager.getConnection(url, user, password);
             PreparedStatement pstmt = conn.prepareStatement(query)) {

            pstmt.setString(1, "Mumbai");
            ResultSet rs = pstmt.executeQuery();

            System.out.println("Query executed successfully. Records found:");
            while(rs.next()){
                System.out.println("ID: " + rs.getInt("id") + ", Name: " + rs.getString("name"));
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}