项目结构

相关源文件

• .gitignore
• shadowsocks-csharp/Encryption/CircularBuffer/ByteCircularBuffer.cs
• shadowsocks-csharp/FodyWeavers.xml
• shadowsocks-csharp/FodyWeavers.xsd
• shadowsocks-csharp/Model/LogViewerConfig.cs
• shadowsocks-csharp/Properties/Resources.Designer.cs
• shadowsocks-csharp/Properties/Resources.resx
• shadowsocks-csharp/Properties/Settings.Designer.cs
• shadowsocks-csharp/Properties/Settings.settings
• shadowsocks-csharp/Settings.cs
• shadowsocks-csharp/app.config
• shadowsocks-csharp/packages.config
• shadowsocks-csharp/shadowsocks-csharp.csproj
• test/ShadowsocksTest.csproj
• test/app.config
• test/packages.config

本文档详细介绍了 Shadowsocks Windows 客户端的代码库组织、构建系统、项目依赖和目录布局。它为理解代码库的结构和不同组件的组织方式提供了参考。有关高级架构和组件交互的信息，请参阅架构。

构建系统和项目配置

Shadowsocks Windows 客户端是一个 WinForms/WPF 混合应用程序，目标框架为 .NET Framework 4.8。该项目使用 MSBuild 作为其构建系统，并通过主项目文件进行配置。

来源：shadowsocks-csharp/shadowsocks-csharp.csproj1-456 shadowsocks-csharp/app.config1-104 shadowsocks-csharp/packages.config1-38 shadowsocks-csharp/FodyWeavers.xml1-6 test/ShadowsocksTest.csproj1-101

项目文件结构

主项目文件定义了程序集信息、构建配置、依赖项和编译文件

• 目标框架: .NET Framework 4.8
• 程序集名称: Shadowsocks
• 输出类型: Windows 可执行文件 (WinExe)
• 目标平台: x86 架构
• 应用程序图标: shadowsocks.ico
• 项目类型 GUID: 包含 WPF (60DC8134-EBA5-43B8-BCC9-BB4BC16C2548)

构建配置

项目定义了两种主要构建配置

配置	平台	优化	调试符号	常量
调试	x86	已禁用	完整版	TRACE;DEBUG
发布	x86	已启用	已启用	TRACE

来源：shadowsocks-csharp/shadowsocks-csharp.csproj47-67

构建过程增强

项目使用多种构建增强工具

1. Costura.Fody: 将依赖项嵌入到输出程序集中，创建单个可执行文件
2. ReactiveUI.Fody: 为 ReactiveUI 提供编译时增强
3. Caseless.Fody: 添加不区分大小写的字符串比较功能

来源：shadowsocks-csharp/FodyWeavers.xml1-6

目录结构与组织

代码库遵循结构化组织，将关注点分离到逻辑目录中。下图显示了主要的目录结构

来源：shadowsocks-csharp/shadowsocks-csharp.csproj220-334

源文件组织

源代码文件（.cs 文件）按功能组织在逻辑目录结构中。以下是主要命名空间及其对应的目录

控制器组件

Controller 目录包含核心业务逻辑和服务管理

• ShadowsocksController.cs: 管理所有应用程序服务的中央控制器
• Service/: 处理网络服务，如 TCP/UDP 中继、PAC 服务器等。
• Strategy/: 实现服务器选择策略
• System/: 管理操作系统集成，如热键、自动启动等。

模型组件

Model 目录包含数据模型和配置类

• Configuration.cs: 主应用程序配置
• Server.cs: 服务器配置模型
• LogViewerConfig.cs: 日志查看器设置
• ForwardProxyConfig.cs, HotKeyConfig.cs, etc.: 各种配置模型
• Geosite/: 用于 PAC 规则的 Geosite 数据模型

UI 组件

用户界面（UI）分为传统的 WinForms 和 WPF 实现

• View/: WinForms 用户界面组件

  • ConfigForm.cs: 服务器配置用户界面
  • LogForm.cs: 日志查看器用户界面
  • MenuViewController.cs: 系统托盘上下文菜单控制器

• Views/: 采用 MVVM 模式的 WPF 用户界面组件

  • ServerSharingView.xaml.cs: 服务器共享用户界面
  • HotkeysView.xaml.cs: 热键配置用户界面
  • 其他对话框和配置视图

• ViewModels/: 遵循 MVVM 模式的 WPF 用户界面视图模型

代理和加密

这些组件实现了核心代理和加密功能

• Proxy/: 代理协议实现

  • DirectConnect.cs, HttpProxy.cs, Socks5Proxy.cs: 各种代理类型
  • IProxy.cs: 代理接口

• Encryption/: 加密实现

  • AEAD/: AEAD 加密实现
  • Stream/: 流密码实现
  • EncryptorFactory.cs: 加密器创建工厂
  • IEncryptor.cs: 加密器接口

实用工具和支持

• Util/: 实用函数和辅助类
• Localization/: 国际化资源

来源：shadowsocks-csharp/shadowsocks-csharp.csproj220-334

依赖管理

项目使用 NuGet 进行依赖管理，包定义在 packages.config 中。主要依赖项包括

来源：shadowsocks-csharp/packages.config1-38

主要 NuGet 包包括

类别	包	目的
MVVM 框架	ReactiveUI 12.1.5	响应式编程 MVVM 实现
日志记录	NLog 4.7.6	灵活的日志框架
序列化	Newtonsoft.Json 13.0.3	JSON 序列化/反序列化
序列化	Google.Protobuf 3.27.2	Protocol Buffers 实现
构建	Costura.Fody 4.1.0	依赖项嵌入到可执行文件
用户界面 (UI)	AvalonEdit 6.0.1	WPF 的文本编辑器组件
用户界面 (UI)	MdXaml 1.6.0	Markdown 渲染组件
用户界面 (UI)	WPFLocalizeExtension 3.8.0	WPF 本地化支持
用户界面 (UI)	ZXing.Net 0.16.6	二维码生成与读取
系统	GlobalHotKey 1.1.0	全局热键支持
系统	CommandLineParser 2.8.0	命令行参数解析

资源管理

应用程序包含通过 .resx 文件管理的多个嵌入式资源和资产

来源：shadowsocks-csharp/Properties/Resources.resx1-166 shadowsocks-csharp/Properties/Resources.Designer.cs1-256 shadowsocks-csharp/shadowsocks-csharp.csproj335-344

应用程序结合使用了以下机制

1. 嵌入式二进制资源:

   • 原生库：libsscrypto.dll.gz
   • 工具：privoxy.exe.gz, sysproxy.exe.gz, sysproxy64.exe.gz

2. 嵌入式文本资源:

   • PAC 脚本：abp.js
   • 配置模板：privoxy_conf.txt, user-rule.txt
   • 本地化数据：i18n.csv
   • 日志配置：NLog.config

3. 图像资源:

   • 应用程序图标：ss32Fill.png, ss32In.png, ss32Out.png, 等。
   • 应用程序标志：ssw128.png

4. 本地化资源:

   • 用于 UI 字符串的多种语言特定资源文件（.resx）

测试项目结构

测试项目（test/ShadowsocksTest.csproj）为核心功能提供了单元测试

• 直接引用主项目
• 包含特定功能的测试文件
  • Sip003PluginTest.cs: SIP003 插件功能测试
  • UrlTest.cs: URL 解析测试
  • UnitTest.cs: 通用单元测试

测试项目使用 MSTest 进行测试，并与主项目共享一些依赖项。

来源：test/ShadowsocksTest.csproj1-101 test/app.config1-20 test/packages.config1-4

构建输出与部署

构建输出结构由项目配置决定

配置	输出路径	优化	调试信息
调试 (x86)	bin\x86\Debug\	已禁用	完整版
发布 (x86)	bin\x86\Release\	已启用	仅 PDB

应用程序构建为独立的、通过 Costura.Fody 嵌入依赖项的可执行文件，从而简化了部署过程，仅需要主可执行文件即可。

来源：shadowsocks-csharp/shadowsocks-csharp.csproj47-67 .gitignore1-367

应用配置

应用程序使用多种配置机制

1. App.config file: 定义运行时设置、程序集绑定重定向和用户设置架构
2. 用户设置: 通过 .NET 设置基础设施实现，用于存储用户界面偏好设置
3. JSON 配置: 以 JSON 格式存储的运行时配置，用于服务器配置文件和选项

设置的持久化通过 Model 命名空间中的各种模型类进行管理，大部分设置在运行时以 JSON 文件形式存储。

来源：shadowsocks-csharp/app.config1-104 shadowsocks-csharp/Properties/Settings.settings1-21 shadowsocks-csharp/Properties/Settings.Designer.cs1-87 shadowsocks-csharp/Model/LogViewerConfig.cs1-94