// ✅ 正确示例
namespace FileManager {
    public class FileProcessor : Object {
        private const int MAX_BUFFER_SIZE = 4096;
        private string _file_path;
        private GLib.List<string> _lines;

        public string file_path {
            get { return _file_path; }
            set { _file_path = value; }
        }

        public signal void line_processed (string line);

        public FileProcessor (string file_path) {
            Object (file_path: file_path);
        }

        public async void process_file () throws GLib.Error {
            var file = GLib.File.new_for_path (_file_path);
            var stream = yield file.read_async (GLib.Priority.DEFAULT, null);
            // ...
        }

        private bool validate_path (string path) {
            return path.length > 0 && !path.contains ("..");
        }
    }
}

// ✅ 使用 4 个空格缩进（不用 Tab）
public class Example : Object {
    public string name { get; set; }

    // 方法之间空一行
    public void method_a () {
        if (condition) {
            // 代码
        }
    }

    // 长参数列表换行对齐
    public void long_method (
        string param1,
        int param2,
        double param3,
        bool param4
    ) {
        // 代码
    }
}

// ✅ 方法调用换行
var result = some_object
    .method_a ()
    .method_b ()
    .method_c ();

// ✅ 条件表达式换行
if (condition_a
    && condition_b
    || condition_c) {
    // 代码
}

/**
 * 用户管理服务
 *
 * 提供用户的增删改查功能，支持异步操作。
 * 所有数据变更会通过 D-Bus 广播。
 *
 * 示例：
 * {{{
 * var service = new UserService ();
 * var user = yield service.create_user ("alice", "[email protected]");
 * }}}
 *
 * @since 1.0.0
 */
public class UserService : Object {
    /**
     * 创建新用户
     *
     * @param name 用户名，必须唯一
     * @param email 邮箱地址
     * @return 新创建的用户对象
     * @throws ValidationError 参数验证失败
     * @throws DatabaseError 数据库操作失败
     */
    public async User create_user (
        string name,
        string email
    ) throws GLib.Error {
        // 验证参数
        if (name.length == 0) {
            throw new ValidationError.EMPTY_NAME ("用户名不能为空");
        }

        // TODO: 实现数据库插入
        // FIXME: 需要处理并发冲突
        // HACK: 临时方案，等待上游修复

        return new User (name, email);
    }
}

// ✅ 单一职责原则：每个类只做一件事
public class UserValidator : Object {
    public bool validate_email (string email) {
        return email.contains ("@") && email.contains (".");
    }

    public bool validate_name (string name) {
        return name.length >= 2 && name.length <= 50;
    }
}

// ❌ 不要在一个类中混合验证和持久化
public class User : Object {
    public bool validate_email () { /* ... */ }
    public void save_to_db () { /* ... */ }
    public void send_email () { /* ... */ }  // 职责过多
}

public class Config : Object {
    // ✅ 使用默认值
    public string host { get; set; default = "localhost"; }
    public int port { get; set; default = 8080; }
    public bool use_ssl { get; set; default = false; }

    // ✅ 只读属性
    public string version { get; default = "1.0.0"; }

    // ✅ 计算属性
    public string base_uri {
        owned get {
            string scheme = use_ssl ? "https" : "http";
            return "%s://%s:%d".printf (scheme, host, port);
        }
    }

    // ✅ 验证属性值
    private int _timeout = 30;
    public int timeout {
        get { return _timeout; }
        set {
            if (value < 0) value = 0;
            if (value > 300) value = 300;
            if (_timeout != value) {
                _timeout = value;
                notify_property ("timeout");
            }
        }
    }
}

public class DataProcessor : Object {
    // ✅ 命名清晰的信号
    public signal void processing_started (string task_id);
    public signal void processing_progress (string task_id, double percent);
    public signal void processing_completed (string task_id, bool success);
    public signal void processing_error (string task_id, GLib.Error error);

    // ✅ 枚举用于状态变化
    public signal void state_changed (AppState old_state, AppState new_state);
}

// ✅ 使用枚举而不是魔术数字
public enum AppState {
    IDLE,
    LOADING,
    PROCESSING,
    ERROR;

    public string to_string () {
        switch (this) {
            case IDLE: return "idle";
            case LOADING: return "loading";
            case PROCESSING: return "processing";
            case ERROR: return "error";
            default: return "unknown";
        }
    }
}

// ✅ 定义领域特定的错误域
errordomain AppError {
    INVALID_INPUT,
    NOT_FOUND,
    PERMISSION_DENIED,
    NETWORK_ERROR,
    DATABASE_ERROR
}

// ✅ 错误传播而不是忽略
public async string fetch_data (string url) throws AppError {
    try {
        var session = new Soup.Session ();
        var message = new Soup.Message ("GET", url);
        var response = yield session.send_and_read_async (
            message, GLib.Priority.DEFAULT, null
        );

        if (message.status_code == 404) {
            throw new AppError.NOT_FOUND ("资源不存在: %s", url);
        }

        if (message.status_code != 200) {
            throw new AppError.NETWORK_ERROR (
                "HTTP %u: %s", message.status_code, url
            );
        }

        return (string) response.get_data ();
    } catch (GLib.Error e) {
        throw new AppError.NETWORK_ERROR ("网络请求失败: %s", e.message);
    }
}

// ✅ 适当的错误日志
public void process (string input) throws AppError {
    if (input.length == 0) {
        critical ("空输入");  // 记录日志
        throw new AppError.INVALID_INPUT ("输入不能为空");
    }
}

public class DataCache : Object {
    // ✅ 使用 GLib 数据结构管理内存
    private GLib.HashTable<string, CacheEntry> cache;

    construct {
        cache = new GLib.HashTable<string, CacheEntry> (
            str_hash, str_equal
        );
    }

    // ✅ 避免循环引用：使用弱引用
    private WeakRef _parent;
    public DataCache? parent {
        owned get { return (DataCache?) _parent.get (); }
        set { _parent = WeakRef (value); }
    }

    // ✅ 清理资源
    public void clear () {
        cache.remove_all ();
    }
}

# 顶层 meson.build
project('my-app', 'vala', 'c',
  version: '1.0.0',
  meson_version: '>= 0.62.0',
  license: 'GPL-3.0-or-later'
)

# 依赖
glib_dep = dependency('glib-2.0', version: '>= 2.74')
gobject_dep = dependency('gobject-2.0')
gtk4_dep = dependency('gtk4', version: '>= 4.10')
libadwaita_dep = dependency('libadwaita-1', version: '>= 1.4')

# 传递给子目录的依赖
app_deps = [glib_dep, gobject_dep, gtk4_dep, libadwaita_dep]

# 子目录
subdir('src')
subdir('data')
subdir('tests')

# src/meson.build
sources = files(
  'main.vala',
  'application.vala',
  'window.vala',
  'preferences.vala',
)

# 工具库（可复用）
utils_sources = files(
  'utils/string-utils.vala',
  'utils/file-utils.vala',
)

utils_lib = static_library('app-utils',
  utils_sources,
  dependencies: [glib_dep, gobject_dep],
)

utils_dep = declare_dependency(
  link_with: utils_lib,
  include_directories: include_directories('utils')
)

# 主应用
executable('my-app',
  sources,
  dependencies: app_deps + [utils_dep],
  install: true
)

# meson_options.txt
option('optimization', type: 'combo', choices: ['0', '1', '2', '3', 's'], default: '2')
option('debug', type: 'boolean', default: true)
option('b_sanitize', type: 'combo', choices: ['none', 'address', 'thread'], default: 'none')

# 发布构建
meson setup build-release \
  --buildtype=release \
  -Doptimization=3 \
  -Ddebug=false

# 调试构建
meson setup build-debug \
  --buildtype=debug \
  -Db_sanitize=address

// ✅ 避免不必要的字符串拼接
// ❌ 差
string result = "";
for (int i = 0; i < 10000; i++) {
    result += i.to_string ();  // 每次创建新字符串
}

// ✅ 好
var builder = new StringBuilder ();
for (int i = 0; i < 10000; i++) {
    builder.append (i.to_string ());
}
string result = builder.str;

// ✅ 使用合适的数据结构
// 频繁查找 → HashTable
var map = new GLib.HashTable<string, User> (str_hash, str_equal);

// 有序数据 → Array
var array = new GLib.Array<int> ();

// 频繁头部操作 → Queue
var queue = new GLib.Queue<string> ();

// ✅ 预分配数组容量
var array = new GLib.Array<string> ();
array.set_size (1000);  // 预分配

// ✅ 使用 owned 避免不必要的引用计数
public owned string get_full_name () {
    return first_name + " " + last_name;  // 直接返回所有权
}

// ✅ 缓存频繁访问的值
private int? _cached_hash = null;
public int get_hash () {
    if (_cached_hash == null) {
        _cached_hash = compute_hash ();
    }
    return _cached_hash;
}

// ✅ 使用 async 避免阻塞主线程
public async void load_data () {
    // 并行加载
    var task1 = fetch_users ();
    var task2 = fetch_posts ();
    var task3 = fetch_comments ();

    yield task1;
    yield task2;
    yield task3;
}

// ✅ 使用 Cancellable 及时取消
public async void search (string query, GLib.Cancellable? cancellable) {
    if (cancellable != null && cancellable.is_cancelled ()) {
        return;
    }

    // 执行搜索...
}

// ✅ 批量操作减少 I/O
public async void save_all (GLib.List<Item> items) throws GLib.Error {
    var builder = new StringBuilder ();
    foreach (var item in items) {
        builder.append (item.serialize ());
        builder.append_c ('\n');
    }

    // 一次性写入
    yield write_file_async ("/tmp/data.txt", builder.str);
}

void main () {
    // GLib 日志级别（从低到高）
    debug ("调试信息，仅开发时可见");
    message ("普通消息");
    warning ("警告信息");
    critical ("严重错误");
    printerr ("错误信息\n");

    // 设置日志级别
    GLib.Log.set_handler (
        null,
        GLib.LogLevelFlags.LEVEL_DEBUG,
        (log_domain, log_level, message) => {
            // 自定义日志处理
        }
    );
}

# 编译时包含调试信息
valac -g myapp.vala -o myapp

# 或使用 Meson
meson setup build --buildtype=debug
ninja -C build

# 使用 GDB
gdb ./build/src/myapp

# GDB 常用命令
(gdb) break main              # 设置断点
(gdb) break application.vala:42  # 在文件行号设置断点
(gdb) run                     # 运行程序
(gdb) next                    # 下一行
(gdb) step                    # 进入函数
(gdb) print variable_name     # 打印变量
(gdb) backtrace               # 查看调用栈
(gdb) info locals             # 查看局部变量

# 检测内存泄漏
valgrind --leak-check=full --show-leak-kinds=all ./build/src/myapp

# 检测线程错误
valgrind --tool=helgrind ./build/src/myapp

# 生成调用图
valgrind --tool=callgrind ./build/src/myapp
callgrind_annotate callgrind.out.12345

# meson.build
if get_option('sanitize')
  add_project_arguments('-fsanitize=address', language: 'c')
  add_project_link_arguments('-fsanitize=address', language: 'c')
endif

meson setup build -Dsanitize=true
ninja -C build
./build/src/myapp  # 自动检测内存错误

void main () {
    // 打印对象属性
    var obj = new MyObject ();

    // 列出所有属性
    var obj_class = (ObjectClass) typeof (MyObject).class_ref ();
    uint n_props;
    var props = obj_class.list_properties (out n_props);
    for (uint i = 0; i < n_props; i++) {
        print ("属性: %s (%s)\n",
               props[i].name,
               props[i].value_type.name ());
    }

    // 检查信号
    uint[] signal_ids = GLib.Signal.list_ids (typeof (MyObject));
    foreach (var id in signal_ids) {
        print ("信号: %s\n", GLib.Signal.name (id));
    }

    // 对象生命周期追踪
    obj.weak_ref ((o) => {
        print ("对象 %s 已销毁\n", o.get_type ().name ());
    });
}

# data/com.example.MyApp.desktop.in.in
[Desktop Entry]
Name=My App
Comment=A Vala application
Exec=@bindir@/my-app
Icon=com.example.MyApp
Terminal=false
Type=Application
Categories=GNOME;Utility;
StartupNotify=true

<!-- data/com.example.MyApp.appdata.xml.in -->
<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>com.example.MyApp</id>
  <name>My App</name>
  <summary>A Vala application for GNOME</summary>
  <metadata_license>CC0-1.0</metadata_license>
  <project_license>GPL-3.0-or-later</project_license>

  <description>
    <p>
      这是一个使用 Vala 编写的 GNOME 应用示例。
    </p>
  </description>

  <releases>
    <release version="1.0.0" date="2026-05-10">
      <description>
        <p>初始发布版本。</p>
      </description>
    </release>
  </releases>

  <content_rating type="oars-1.1"/>

  <url type="homepage">https://example.com/my-app</url>
  <url type="bugtracker">https://github.com/example/my-app/issues</url>
</component>

<!-- data/com.example.MyApp.gschema.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<schemalist>
  <schema id="com.example.MyApp"
          path="/com/example/MyApp/">

    <key name="window-width" type="i">
      <default>800</default>
      <summary>窗口宽度</summary>
      <description>应用窗口的宽度</description>
    </key>

    <key name="window-height" type="i">
      <default>600</default>
      <summary>窗口高度</summary>
      <description>应用窗口的高度</description>
    </key>

    <key name="dark-mode" type="b">
      <default>false</default>
      <summary>深色模式</summary>
      <description>是否启用深色模式</description>
    </key>

  </schema>
</schemalist>

public class Preferences : Object {
    private GLib.Settings settings;

    // 绑定到 GSettings
    public int window_width {
        get { return settings.get_int ("window-width"); }
        set { settings.set_int ("window-width", value); }
    }

    public int window_height {
        get { return settings.get_int ("window-height"); }
        set { settings.set_int ("window-height", value); }
    }

    public bool dark_mode {
        get { return settings.get_boolean ("dark-mode"); }
        set { settings.set_boolean ("dark-mode", value); }
    }

    construct {
        settings = new GLib.Settings ("com.example.MyApp");

        // 监听设置变化
        settings.changed.connect ((key) => {
            print ("设置已变化: %s\n", key);
        });
    }

    // 自动绑定到控件
    public void bind_to_window (Adw.ApplicationWindow window) {
        settings.bind ("window-width", window, "default-width",
            GLib.SettingsBindFlags.DEFAULT);
        settings.bind ("window-height", window, "default-height",
            GLib.SettingsBindFlags.DEFAULT);
    }
}

// 使用 gettext
public class MyApp : Adw.Application {
    construct {
        // 初始化国际化
        GLib.Intl.setlocale (GLib.LocaleCategory.ALL, "");
        GLib.Intl.bindtextdomain (Config.GETTEXT_PACKAGE,
            Config.LOCALE_DIR);
        GLib.Intl.bind_textdomain_codeset (Config.GETTEXT_PACKAGE, "UTF-8");
        GLib.Intl.textdomain (Config.GETTEXT_PACKAGE);
    }

    protected override void activate () {
        // 使用 _() 包裹需要翻译的字符串
        var label = new Label (_("Hello, World!"));
        var button = new Button.with_label (_("Click me"));

        // 带格式的翻译
        string message = _("Welcome, %s!").printf (user_name);
    }
}

# data/meson.build
i18n = import('i18n')

# 编译 .desktop 文件
i18n.merge_file(
  input: 'com.example.MyApp.desktop.in.in',
  output: 'com.example.MyApp.desktop',
  type: 'desktop',
  po_dir: '../po',
  install: true,
  install_dir: get_option('datadir') / 'applications'
)

# 编译 AppData 文件
i18n.merge_file(
  input: 'com.example.MyApp.appdata.xml.in',
  output: 'com.example.MyApp.appdata.xml',
  po_dir: '../po',
  install: true,
  install_dir: get_option('datadir') / 'metainfo'
)

// tests/test-utils.vala
public class TestUtils : Object {
    public static void register () {
        Test.add_func ("/utils/string/trim", test_string_trim);
        Test.add_func ("/utils/string/format", test_string_format);
        Test.add_func ("/utils/math/add", test_math_add);
    }

    private static void test_string_trim () {
        assert ("hello" == StringUtils.trim ("  hello  "));
        assert ("hello" == StringUtils.trim ("hello"));
        assert ("" == StringUtils.trim ("   "));
    }

    private static void test_string_format () {
        string result = StringUtils.format_name ("张", "三");
        assert (result == "张 三");
    }

    private static void test_math_add () {
        assert (MathUtils.add (2, 3) == 5);
        assert (MathUtils.add (-1, 1) == 0);
        assert (MathUtils.add (0, 0) == 0);
    }
}

void main (string[] args) {
    Test.init (ref args);
    TestUtils.register ();
    Test.run ();
}

# tests/meson.build
test_utils = executable('test-utils',
  'test-utils.vala',
  dependencies: [glib_dep, gobject_dep, utils_dep],
)

test('unit tests', test_utils)

// tests/test-integration.vala
public class TestIntegration : Object {
    public static void register () {
        Test.add_func ("/integration/database", test_database);
        Test.add_func ("/integration/config", test_config);
    }

    private static void test_database () {
        // 使用临时数据库
        string tmp_path = GLib.DirUtils.make_tmp ("test-db-XXXXXX");
        try {
            var db = new Database (tmp_path + "/test.db");
            db.create_table ("users");
            db.insert ("users", "name", "Alice");

            var result = db.query ("SELECT name FROM users");
            assert (result.length == 1);
            assert (result[0] == "Alice");
        } catch (GLib.Error e) {
            assert_not_reached ();
        }

        // 清理
        GLib.DirUtils.remove (tmp_path);
    }

    private static void test_config () {
        var config = new Config ();
        config.host = "localhost";
        config.port = 8080;
        assert (config.base_uri == "http://localhost:8080");

        config.use_ssl = true;
        assert (config.base_uri == "https://localhost:8080");
    }
}

void main (string[] args) {
    Test.init (ref args);
    TestIntegration.register ();
    Test.run ();
}

# meson.build
project('my-app', 'vala', 'c',
  version: '1.2.3',
)

# 在代码中使用
config = configuration_data()
config.set('VERSION', meson.project_version())
config.set('APP_ID', 'com.example.MyApp')

configure_file(
  input: 'config.vala.in',
  output: 'config.vala',
  configuration: config
)

// src/config.vala.in
namespace Config {
    public const string VERSION = "@VERSION@";
    public const string APP_ID = "@APP_ID@";
    public const string GETTEXT_PACKAGE = "@APP_ID@";
    public const string LOCALE_DIR = "@LOCALE_DIR@";
}

// ✅ 始终验证外部输入
public bool validate_username (string username) throws AppError {
    if (username.length == 0) {
        throw new AppError.INVALID_INPUT ("用户名不能为空");
    }
    if (username.length > 50) {
        throw new AppError.INVALID_INPUT ("用户名过长");
    }
    // 只允许字母、数字、下划线
    if (!/^[\w]+$/.match (username)) {
        throw new AppError.INVALID_INPUT ("用户名包含非法字符");
    }
    return true;
}

// ✅ 路径遍历防护
public string safe_path (string base_dir, string filename) throws AppError {
    string full_path = GLib.Path.build_filename (base_dir, filename);
    string canonical = GLib.canonicalize_filename (full_path, base_dir);

    if (!canonical.has_prefix (base_dir)) {
        throw new AppError.PERMISSION_DENIED ("路径遍历攻击");
    }

    return canonical;
}

// ✅ 不要在日志中输出敏感信息
public void handle_login (string username, string password) {
    debug ("用户登录: %s", username);      // ✅ OK
    // debug ("密码: %s", password);       // ❌ 不要这样做

    // ✅ 使用后立即清除
    uint8[] password_bytes = password.data;
    // ... 使用密码
    GLib.memory_set (password_bytes, 0, password_bytes.length);
}

// 最小 GTK 应用
using Gtk;
using Adw;

public class App : Adw.Application {
    public App () {
        Object (application_id: "com.example.App",
                flags: ApplicationFlags.FLAGS_NONE);
    }
    protected override void activate () {
        var win = new Adw.ApplicationWindow (this) {
            title = "Hello", default_width = 400, default_height = 300
        };
        win.set_content (new Label ("Hello, Vala!"));
        win.present ();
    }
}

void main (string[] args) { new App ().run (args); }

# 编译命令
valac --pkg gtk4 --pkg libadwaita-1 -o app app.vala

# Meson 构建
meson setup build && ninja -C build