Skip to main content

gitflow_core/
release.rs

1//! Release 领域类型与平台抽象。
2//!
3//! 定义了 Release(版本发布)的数据表示、创建参数,以及跨平台
4//! 实现所需的 [`ReleaseProvider`] trait。GitHub、GitLab、GitCode
5//! 等平台实现都需实现该 trait,使上层命令层可统一消费。
6
7use async_trait::async_trait;
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10
11use crate::{Result, paging::Paged, types::UserSummary};
12
13/// Release 数据。
14///
15/// 由平台实现填充并返回给上层命令。字段命名与 `gh release`
16/// CLI 输出的 JSON 字段对齐(camelCase)。
17#[derive(Debug, Clone, Serialize, Deserialize)]
18#[serde(rename_all = "camelCase")]
19pub struct ReleaseData {
20    /// Release 的 numeric ID(list 命令可能不包含此字段)。
21    #[serde(default, alias = "databaseId")]
22    pub id: u64,
23    /// 关联的 Git tag 名。
24    pub tag_name: String,
25    /// Release 标题(可选)。
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub name: Option<String>,
28    /// Release 正文(Markdown,list 命令可能不包含此字段)。
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub body: Option<String>,
31    /// 是否为草稿 Release。
32    #[serde(alias = "isDraft")]
33    pub draft: bool,
34    /// 是否为预发布版本。
35    #[serde(alias = "isPrerelease")]
36    pub prerelease: bool,
37    /// Release 作者(list 命令可能不包含此字段)。
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub author: Option<UserSummary>,
40    /// 创建时间(UTC)。API 未返回该字段时为 `None`——绝不用当前时间伪造。
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub created_at: Option<DateTime<Utc>>,
43    /// 发布时间(UTC),草稿 Release 为 None。
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub published_at: Option<DateTime<Utc>>,
46    /// Release 的 Web URL(list 命令可能不包含此字段)。
47    #[serde(default)]
48    pub url: String,
49}
50
51/// 创建 Release 所需参数。
52#[derive(Debug, Clone)]
53pub struct CreateReleaseArgs {
54    /// 关联的 Git tag 名。
55    pub tag_name: String,
56    /// Release 标题(可选)。
57    pub name: Option<String>,
58    /// Release 正文(Markdown)。
59    pub body: Option<String>,
60    /// 是否以草稿方式创建。
61    pub draft: bool,
62    /// 是否为预发布版本。
63    pub prerelease: bool,
64    /// 目标 commitish(可选,默认当前分支 HEAD)。
65    pub target_commitish: Option<String>,
66}
67
68/// Release 操作的平台抽象。
69///
70/// 所有平台实现(GitHub/GitLab/GitCode)都必须实现此 trait,
71/// 以提供统一的 Release 创建、列表、查看、编辑、资源上传/下载
72/// 及删除能力。
73///
74/// # Errors
75///
76/// 所有方法在平台调用失败、反序列化失败或鉴权失败时返回
77/// [`CoreError`](crate::CoreError)。
78///
79/// [`CoreError`]: crate::CoreError
80#[async_trait]
81pub trait ReleaseProvider: std::fmt::Debug + Send + Sync {
82    /// 创建一条新 Release,返回平台生成的完整数据。
83    ///
84    /// # Errors
85    ///
86    /// 当平台 API 调用失败或参数非法时返回错误。
87    async fn create(&self, args: CreateReleaseArgs) -> Result<ReleaseData>;
88
89    /// 列出仓库的 Release。
90    ///
91    /// `limit` 为 `None` 时取至 [`crate::paging::DEFAULT_LIST_LIMIT`]。
92    /// 返回的 [`Paged`] 携带截断标志。
93    ///
94    /// # Errors
95    ///
96    /// 当平台 API 调用失败时返回错误。
97    async fn list(&self, limit: Option<u32>) -> Result<Paged<ReleaseData>>;
98
99    /// 查看指定 tag 的 Release 详情。
100    ///
101    /// # Errors
102    ///
103    /// 当 Release 不存在或平台 API 调用失败时返回错误。
104    async fn view(&self, tag_name: &str) -> Result<ReleaseData>;
105
106    /// 编辑指定 Release 的元数据,返回更新后的数据。
107    ///
108    /// # Errors
109    ///
110    /// 当 Release 不存在或平台 API 调用失败时返回错误。
111    async fn edit(&self, tag_name: &str, args: CreateReleaseArgs) -> Result<ReleaseData>;
112
113    /// 上传资源文件到指定 Release。
114    ///
115    /// `file_path` 为本地文件路径,`asset_name` 为在 Release
116    /// 中显示的资源名。
117    ///
118    /// # Errors
119    ///
120    /// 当 Release 不存在、文件读取失败或平台 API 调用失败时返回错误。
121    async fn upload_asset(&self, tag_name: &str, file_path: &str, asset_name: &str) -> Result<()>;
122
123    /// 下载指定 Release 的资源文件到本地路径。
124    ///
125    /// # Errors
126    ///
127    /// 当 Release 不存在、资源不存在或写入失败时返回错误。
128    async fn download_asset(&self, tag_name: &str, asset_name: &str, dest_path: &str)
129    -> Result<()>;
130
131    /// 删除指定 Release。
132    ///
133    /// # Errors
134    ///
135    /// 当 Release 不存在或平台 API 调用失败时返回错误。
136    async fn delete(&self, tag_name: &str) -> Result<()>;
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    fn sample_release_json() -> &'static str {
144        r#"{
145            "id": 1001,
146            "tagName": "v1.0.0",
147            "name": "Version 1.0.0",
148            "body": "Initial stable release",
149            "draft": false,
150            "prerelease": false,
151            "author": {"login": "octocat", "id": "1"},
152            "createdAt": "2026-01-01T00:00:00Z",
153            "publishedAt": "2026-01-15T12:00:00Z",
154            "url": "https://github.com/octocat/hello-world/releases/tag/v1.0.0"
155        }"#
156    }
157
158    #[test]
159    fn test_should_deserialize_release_data_from_json() {
160        let json = sample_release_json();
161        let release: ReleaseData = serde_json::from_str(json).expect("valid ReleaseData JSON");
162
163        assert_eq!(release.id, 1001);
164        assert_eq!(release.tag_name, "v1.0.0");
165        assert_eq!(release.name.as_deref(), Some("Version 1.0.0"));
166        assert_eq!(release.body.as_deref(), Some("Initial stable release"));
167        assert!(!release.draft);
168        assert!(!release.prerelease);
169        assert_eq!(release.author.as_ref().unwrap().login, "octocat");
170        assert_eq!(release.author.as_ref().unwrap().id, "1");
171        assert_eq!(
172            release.url,
173            "https://github.com/octocat/hello-world/releases/tag/v1.0.0"
174        );
175    }
176
177    #[test]
178    fn test_should_roundtrip_release_data_via_serde() {
179        let json = sample_release_json();
180        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
181        let re_serialized = serde_json::to_string(&release).expect("serialize");
182        let round_tripped: ReleaseData =
183            serde_json::from_str(&re_serialized).expect("re-deserialize");
184
185        assert_eq!(round_tripped.id, release.id);
186        assert_eq!(round_tripped.tag_name, release.tag_name);
187        assert_eq!(round_tripped.name, release.name);
188        assert_eq!(round_tripped.body, release.body);
189        assert_eq!(round_tripped.draft, release.draft);
190        assert_eq!(round_tripped.prerelease, release.prerelease);
191        assert_eq!(round_tripped.created_at, release.created_at);
192        assert_eq!(round_tripped.published_at, release.published_at);
193        assert_eq!(round_tripped.url, release.url);
194    }
195
196    #[test]
197    fn test_should_deserialize_draft_release_with_null_optional_fields() {
198        let json = r#"{
199            "id": 5,
200            "tagName": "v0.1.0-draft",
201            "name": null,
202            "body": null,
203            "draft": true,
204            "prerelease": true,
205            "author": {"login": "dev", "id": "99"},
206            "createdAt": "2026-03-01T00:00:00Z",
207            "publishedAt": null,
208            "url": "https://example.com/releases/5"
209        }"#;
210        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
211        assert!(release.draft);
212        assert!(release.prerelease);
213        assert!(release.name.is_none());
214        assert!(release.body.is_none());
215        assert!(release.published_at.is_none());
216    }
217
218    #[test]
219    fn test_should_omit_none_fields_on_serialize() {
220        let json = sample_release_json();
221        let mut release: ReleaseData = serde_json::from_str(json).expect("deserialize");
222        release.name = None;
223        release.body = None;
224        release.published_at = None;
225        let serialized = serde_json::to_string(&release).expect("serialize");
226        assert!(!serialized.contains("null"));
227        assert!(!serialized.contains("\"name\":"));
228        assert!(!serialized.contains("\"body\":"));
229        assert!(!serialized.contains("\"publishedAt\":"));
230    }
231
232    #[test]
233    fn test_should_deserialize_release_with_missing_created_at_as_none() {
234        let json = r#"{
235            "id": 7,
236            "tagName": "v0.5.0",
237            "draft": false,
238            "prerelease": false,
239            "url": "https://example.com/releases/7"
240        }"#;
241        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
242        assert!(
243            release.created_at.is_none(),
244            "missing createdAt must deserialize to None, not error or a fabricated timestamp"
245        );
246    }
247
248    #[test]
249    fn test_should_omit_created_at_when_none_on_serialize() {
250        let json = sample_release_json();
251        let mut release: ReleaseData = serde_json::from_str(json).expect("deserialize");
252        release.created_at = None;
253        let serialized = serde_json::to_string(&release).expect("serialize");
254        assert!(!serialized.contains("\"createdAt\""));
255    }
256
257    #[test]
258    fn test_should_serialize_camel_case_fields() {
259        let json = sample_release_json();
260        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
261        let serialized = serde_json::to_string(&release).expect("serialize");
262        assert!(serialized.contains("\"tagName\""));
263        assert!(serialized.contains("\"createdAt\""));
264        assert!(serialized.contains("\"publishedAt\""));
265        assert!(!serialized.contains("\"tag_name\""));
266        assert!(!serialized.contains("\"created_at\""));
267        assert!(!serialized.contains("\"published_at\""));
268    }
269
270    #[test]
271    fn test_create_release_args_debug_derive() {
272        let args = CreateReleaseArgs {
273            tag_name: "v1.0.0".into(),
274            name: Some("v1".into()),
275            body: None,
276            draft: false,
277            prerelease: false,
278            target_commitish: Some("abc123".into()),
279        };
280        let debug = format!("{args:?}");
281        assert!(debug.contains("CreateReleaseArgs"));
282        assert!(debug.contains("v1.0.0"));
283    }
284
285    // --- Alias deserialization tests ---
286
287    #[test]
288    fn test_should_deserialize_is_draft_alias() {
289        let json = r#"{
290            "id": 1,
291            "tagName": "v0.1.0",
292            "isDraft": true,
293            "prerelease": false,
294            "createdAt": "2026-01-01T00:00:00Z"
295        }"#;
296        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
297        assert!(release.draft);
298        assert!(!release.prerelease);
299    }
300
301    #[test]
302    fn test_should_deserialize_is_prerelease_alias() {
303        let json = r#"{
304            "id": 1,
305            "tagName": "v0.1.0",
306            "draft": false,
307            "isPrerelease": true,
308            "createdAt": "2026-01-01T00:00:00Z"
309        }"#;
310        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
311        assert!(!release.draft);
312        assert!(release.prerelease);
313    }
314
315    #[test]
316    fn test_should_deserialize_database_id_alias() {
317        let json = r#"{
318            "databaseId": 42,
319            "tagName": "v1.0.0",
320            "draft": false,
321            "prerelease": false,
322            "createdAt": "2026-01-01T00:00:00Z"
323        }"#;
324        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
325        assert_eq!(release.id, 42);
326    }
327
328    #[test]
329    fn test_should_reject_duplicate_id_and_database_id() {
330        let json = r#"{
331            "id": 10,
332            "databaseId": 99,
333            "tagName": "v1.0.0",
334            "draft": false,
335            "prerelease": false,
336            "createdAt": "2026-01-01T00:00:00Z"
337        }"#;
338        let result: std::result::Result<ReleaseData, _> = serde_json::from_str(json);
339        // Serde rejects duplicate fields when both the primary name and an alias
340        // are present in the same JSON object.
341        assert!(result.is_err());
342    }
343
344    // --- Default / optional field tests ---
345
346    #[test]
347    fn test_should_default_url_to_empty_string() {
348        let json = r#"{
349            "id": 1,
350            "tagName": "v0.1.0",
351            "draft": false,
352            "prerelease": false,
353            "createdAt": "2026-01-01T00:00:00Z"
354        }"#;
355        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
356        assert_eq!(release.url, "");
357    }
358
359    #[test]
360    fn test_should_default_id_to_zero() {
361        let json = r#"{
362            "tagName": "v0.1.0",
363            "draft": false,
364            "prerelease": false,
365            "createdAt": "2026-01-01T00:00:00Z"
366        }"#;
367        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
368        assert_eq!(release.id, 0);
369    }
370
371    // --- Skip-serializing-if tests for optional fields ---
372
373    #[test]
374    fn test_should_skip_author_when_none_on_serialize() {
375        let json = r#"{
376            "id": 1,
377            "tagName": "v1.0.0",
378            "draft": false,
379            "prerelease": false,
380            "createdAt": "2026-01-01T00:00:00Z",
381            "url": ""
382        }"#;
383        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
384        assert!(release.author.is_none());
385        let serialized = serde_json::to_string(&release).expect("serialize");
386        assert!(!serialized.contains("\"author\""));
387    }
388
389    // --- Debug format tests ---
390
391    #[test]
392    fn test_release_data_should_have_debug_format() {
393        let json = sample_release_json();
394        let release: ReleaseData = serde_json::from_str(json).expect("deserialize");
395        let debug = format!("{release:?}");
396        assert!(debug.contains("ReleaseData"));
397        assert!(debug.contains("v1.0.0"));
398        assert!(debug.contains("Version 1.0.0"));
399    }
400
401    // --- CreateReleaseArgs additional tests ---
402
403    #[test]
404    fn test_should_create_release_args_with_minimal_fields() {
405        let args = CreateReleaseArgs {
406            tag_name: "v1.0.0".into(),
407            name: None,
408            body: None,
409            draft: false,
410            prerelease: false,
411            target_commitish: None,
412        };
413        assert_eq!(args.tag_name, "v1.0.0");
414        assert!(args.name.is_none());
415        assert!(args.body.is_none());
416        assert!(!args.draft);
417        assert!(!args.prerelease);
418        assert!(args.target_commitish.is_none());
419    }
420
421    #[test]
422    fn test_should_create_release_args_with_all_fields() {
423        let args = CreateReleaseArgs {
424            tag_name: "v2.0.0".into(),
425            name: Some("Major Release".into()),
426            body: Some("## Breaking Changes\n- ...".into()),
427            draft: true,
428            prerelease: true,
429            target_commitish: Some("main".into()),
430        };
431        assert_eq!(args.tag_name, "v2.0.0");
432        assert_eq!(args.name.as_deref(), Some("Major Release"));
433        assert_eq!(args.body.as_deref(), Some("## Breaking Changes\n- ..."));
434        assert!(args.draft);
435        assert!(args.prerelease);
436        assert_eq!(args.target_commitish.as_deref(), Some("main"));
437    }
438
439    #[test]
440    fn test_create_release_args_should_be_cloneable() {
441        let args = CreateReleaseArgs {
442            tag_name: "v1.0.0".into(),
443            name: Some("v1".into()),
444            body: Some("body".into()),
445            draft: true,
446            prerelease: false,
447            target_commitish: Some("abc123".into()),
448        };
449        let cloned = args.clone();
450        assert_eq!(cloned.tag_name, args.tag_name);
451        assert_eq!(cloned.name, args.name);
452        assert_eq!(cloned.body, args.body);
453        assert_eq!(cloned.draft, args.draft);
454        assert_eq!(cloned.prerelease, args.prerelease);
455        assert_eq!(cloned.target_commitish, args.target_commitish);
456    }
457}