fix(api): 补齐单次请求模板变量与请求头支持

README.md

@@ -695,6 +695,16 @@ Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-s
 
 # With query parameters
 gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
+
+# Reuse --owner/--repo placeholders in a single request
+gitlink-cli api GET /:owner/:repo/issues --owner Gitlink --repo gitlink-cli --query 'page=1&limit=5'
+
+# Render one-off template variables in path, query, body, and headers
+gitlink-cli api POST /{{owner}}/{{repo}}/issues/{{number}}/journals \
+  --var owner=Gitlink --var repo=gitlink-cli --var number=42 --var actor=codex \
+  --query 'notify={{actor}}' \
+  --header 'X-Actor: {{actor}}' \
+  --body '{"notes":"handled by {{actor}}"}'
 ```
 
 ## Global Parameters

README.zh-CN.md

@@ -569,6 +569,16 @@ Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-s
 
 # 带查询参数
 gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
+
+# 鍗曟璇锋眰涓洿鎺ュ鐢?--owner / --repo 鍗犱綅绗?
+gitlink-cli api GET /:owner/:repo/issues --owner Gitlink --repo gitlink-cli --query 'page=1&limit=5'
+
+# 鍦?path / query / body / header 涓覆鏌撲竴娆℃€фā鏉垮彉閲?
+gitlink-cli api POST /{{owner}}/{{repo}}/issues/{{number}}/journals \
+  --var owner=Gitlink --var repo=gitlink-cli --var number=42 --var actor=codex \
+  --query 'notify={{actor}}' \
+  --header 'X-Actor: {{actor}}' \
+  --body '{"notes":"handled by {{actor}}"}'
 ```
 
 ## 全局参数

cmd/api/api.go

@@ -5,14 +5,17 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net/http"
 	"net/url"
 	"os"
+	"sort"
 	"strings"
 
 	"github.com/spf13/cobra"
 
 	"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
 	"github.com/gitlink-org/gitlink-cli/internal/client"
+	gitcontext "github.com/gitlink-org/gitlink-cli/internal/context"
 	"github.com/gitlink-org/gitlink-cli/internal/i18n"
 	"github.com/gitlink-org/gitlink-cli/internal/output"
 )
@@ -29,6 +32,7 @@ func NewAPICmd(translators ...*i18n.Translator) *cobra.Command {
 		Example: `  gitlink-cli api GET /users/me
   gitlink-cli api GET /projects --query 'page=1&limit=10'
   gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"Bug","description":"..."}'
+  gitlink-cli api GET /{{owner}}/{{repo}}/pulls --var owner=Gitlink --var repo=gitlink-cli
   gitlink-cli api POST /:owner/:repo/issues --body-file issue.json
   gitlink-cli api --batch-file plan.json --dry-run
   gitlink-cli api --batch-file plan.json --var owner=Gitlink --var repo=gitlink-cli`,
@@ -67,17 +71,6 @@ func runAPI(c *cobra.Command, args []string) error {
 	}
 
 	method := strings.ToUpper(args[0])
-	path := args[1]
-
-	if !strings.HasPrefix(path, "/") {
-		path = "/" + path
-	}
-
-	cli, err := client.New()
-	if err != nil {
-		return err
-	}
-	cli.Debug = cmdutil.Debug
 
 	body, err := readJSONBody(c)
 	if err != nil {
@@ -94,7 +87,23 @@ func runAPI(c *cobra.Command, args []string) error {
 		}
 	}
 
-	env, err := cli.Do(method, path, body, query)
+	headers, err := parseAPIHeaders(c)
+	if err != nil {
+		return err
+	}
+
+	request, err := renderSingleAPIRequest(args[1], query, body, headers, c)
+	if err != nil {
+		return err
+	}
+
+	cli, err := client.New()
+	if err != nil {
+		return err
+	}
+	cli.Debug = cmdutil.Debug
+
+	env, err := cli.DoWithHeaders(method, request.Path, request.Body, request.Query, request.Headers)
 	if err != nil {
 		var apiErr *client.APIError
 		if errors.As(err, &apiErr) {
@@ -157,3 +166,207 @@ func resolveFormat() string {
 	}
 	return f
 }
+
+type singleAPIRequest struct {
+	Path    string
+	Query   url.Values
+	Body    interface{}
+	Headers http.Header
+}
+
+func renderSingleAPIRequest(path string, query url.Values, body interface{}, headers http.Header, c *cobra.Command) (*singleAPIRequest, error) {
+	normalizedPath := normalizeSingleAPIPath(path)
+	if !strings.HasPrefix(normalizedPath, "/") {
+		normalizedPath = "/" + normalizedPath
+	}
+
+	vars, err := resolveSingleRequestVars(c, normalizedPath, query, body, headers)
+	if err != nil {
+		return nil, err
+	}
+
+	renderedPath, err := renderTemplate(normalizedPath, vars)
+	if err != nil {
+		return nil, fmt.Errorf("render path: %w", err)
+	}
+	renderedQuery, err := renderURLValues(query, vars)
+	if err != nil {
+		return nil, fmt.Errorf("render query: %w", err)
+	}
+	renderedBody, err := renderBatchValue(body, vars)
+	if err != nil {
+		return nil, fmt.Errorf("render body: %w", err)
+	}
+	renderedHeaders, err := renderAPIHeaders(headers, vars)
+	if err != nil {
+		return nil, fmt.Errorf("render headers: %w", err)
+	}
+
+	return &singleAPIRequest{
+		Path:    renderedPath,
+		Query:   renderedQuery,
+		Body:    renderedBody,
+		Headers: renderedHeaders,
+	}, nil
+}
+
+func normalizeSingleAPIPath(path string) string {
+	return strings.NewReplacer(":owner", "{{owner}}", ":repo", "{{repo}}").Replace(strings.TrimSpace(path))
+}
+
+func resolveSingleRequestVars(c *cobra.Command, path string, query url.Values, body interface{}, headers http.Header) (map[string]string, error) {
+	vars, err := parseBatchVars(c)
+	if err != nil {
+		return nil, err
+	}
+	if !needsOwnerRepoResolution(path, query, body, headers, vars) {
+		return vars, nil
+	}
+	owner, repo, err := gitcontext.ResolveOwnerRepo(cmdutil.Owner, cmdutil.Repo)
+	if err != nil {
+		return nil, fmt.Errorf("resolve owner/repo for api templates: %w", err)
+	}
+	if _, ok := vars["owner"]; !ok {
+		vars["owner"] = owner
+	}
+	if _, ok := vars["repo"]; !ok {
+		vars["repo"] = repo
+	}
+	return vars, nil
+}
+
+func needsOwnerRepoResolution(path string, query url.Values, body interface{}, headers http.Header, vars map[string]string) bool {
+	if vars["owner"] != "" && vars["repo"] != "" {
+		return false
+	}
+	if strings.Contains(path, "{{owner}}") || strings.Contains(path, "{{repo}}") {
+		return true
+	}
+	for key, values := range query {
+		if strings.Contains(key, "{{owner}}") || strings.Contains(key, "{{repo}}") {
+			return true
+		}
+		for _, value := range values {
+			if strings.Contains(value, "{{owner}}") || strings.Contains(value, "{{repo}}") {
+				return true
+			}
+		}
+	}
+	if containsTemplateVar(body, "owner", "repo") {
+		return true
+	}
+	for key, values := range headers {
+		if strings.Contains(key, "{{owner}}") || strings.Contains(key, "{{repo}}") {
+			return true
+		}
+		for _, value := range values {
+			if strings.Contains(value, "{{owner}}") || strings.Contains(value, "{{repo}}") {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func containsTemplateVar(value interface{}, names ...string) bool {
+	switch typed := value.(type) {
+	case nil:
+		return false
+	case string:
+		for _, name := range names {
+			if strings.Contains(typed, "{{"+name+"}}") {
+				return true
+			}
+		}
+		return false
+	case []interface{}:
+		for _, item := range typed {
+			if containsTemplateVar(item, names...) {
+				return true
+			}
+		}
+		return false
+	case map[string]interface{}:
+		for key, item := range typed {
+			if containsTemplateVar(key, names...) || containsTemplateVar(item, names...) {
+				return true
+			}
+		}
+		return false
+	default:
+		return false
+	}
+}
+
+func parseAPIHeaders(c *cobra.Command) (http.Header, error) {
+	rawHeaders, _ := c.Flags().GetStringSlice("header")
+	if len(rawHeaders) == 0 {
+		return nil, nil
+	}
+	headers := http.Header{}
+	for _, item := range rawHeaders {
+		name, value, ok := strings.Cut(item, ":")
+		if !ok {
+			return nil, fmt.Errorf("invalid --header %q, want key:value", item)
+		}
+		name = strings.TrimSpace(name)
+		value = strings.TrimSpace(value)
+		if name == "" {
+			return nil, fmt.Errorf("invalid --header %q, header name cannot be empty", item)
+		}
+		headers.Add(name, value)
+	}
+	return headers, nil
+}
+
+func renderAPIHeaders(headers http.Header, vars map[string]string) (http.Header, error) {
+	if len(headers) == 0 {
+		return nil, nil
+	}
+	rendered := http.Header{}
+	keys := make([]string, 0, len(headers))
+	for key := range headers {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		renderedKey, err := renderTemplate(key, vars)
+		if err != nil {
+			return nil, err
+		}
+		for _, value := range headers.Values(key) {
+			renderedValue, err := renderTemplate(value, vars)
+			if err != nil {
+				return nil, err
+			}
+			rendered.Add(renderedKey, renderedValue)
+		}
+	}
+	return rendered, nil
+}
+
+func renderURLValues(query url.Values, vars map[string]string) (url.Values, error) {
+	if len(query) == 0 {
+		return nil, nil
+	}
+	rendered := url.Values{}
+	keys := make([]string, 0, len(query))
+	for key := range query {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		renderedKey, err := renderTemplate(key, vars)
+		if err != nil {
+			return nil, err
+		}
+		for _, value := range query[key] {
+			renderedValue, err := renderTemplate(value, vars)
+			if err != nil {
+				return nil, err
+			}
+			rendered.Add(renderedKey, renderedValue)
+		}
+	}
+	return rendered, nil
+}

cmd/api/api_test.go

@@ -4,8 +4,10 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
 	"path/filepath"
+	"reflect"
 	"testing"
 
 	"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
@@ -202,6 +204,107 @@ func TestRunAPINoPrefix(t *testing.T) {
 	}
 }
 
+func TestRunAPISingleRequestTemplatesAndHeaders(t *testing.T) {
+	oldOwner, oldRepo, oldFormat := cmdutil.Owner, cmdutil.Repo, cmdutil.Format
+	cmdutil.Owner = "Gitlink"
+	cmdutil.Repo = "gitlink-cli"
+	cmdutil.Format = "json"
+	t.Cleanup(func() {
+		cmdutil.Owner = oldOwner
+		cmdutil.Repo = oldRepo
+		cmdutil.Format = oldFormat
+	})
+
+	var gotBody map[string]interface{}
+	setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/Gitlink/gitlink-cli/issues.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("state") != "open" {
+			t.Fatalf("state query = %q, want open", r.URL.Query().Get("state"))
+		}
+		if r.URL.Query().Get("repo") != "gitlink-cli" {
+			t.Fatalf("repo query = %q, want gitlink-cli", r.URL.Query().Get("repo"))
+		}
+		if r.Header.Get("X-Repo") != "gitlink-cli" {
+			t.Fatalf("X-Repo = %q, want gitlink-cli", r.Header.Get("X-Repo"))
+		}
+		if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
+			t.Fatalf("decode body: %v", err)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]interface{}{"id": 7})
+	})
+
+	cmd := NewAPICmd()
+	cmd.SetArgs([]string{"POST", "/:owner/:repo/issues"})
+	cmd.Flags().Set("query", "state={{state}}&repo={{repo}}")
+	cmd.Flags().Set("body", `{"subject":"{{title}}","meta":{"owner":"{{owner}}","repo":"{{repo}}"}}`)
+	cmd.Flags().Set("header", "X-Repo: {{repo}}")
+	cmd.Flags().Set("var", "state=open")
+	cmd.Flags().Set("var", "title=Bug report")
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("runAPI template error: %v", err)
+	}
+
+	if gotBody["subject"] != "Bug report" {
+		t.Fatalf("subject = %#v, want Bug report", gotBody["subject"])
+	}
+	meta, _ := gotBody["meta"].(map[string]interface{})
+	if meta["owner"] != "Gitlink" || meta["repo"] != "gitlink-cli" {
+		t.Fatalf("meta = %#v", meta)
+	}
+}
+
+func TestRenderSingleAPIRequestUsesVarsAndOwnerRepo(t *testing.T) {
+	oldOwner, oldRepo := cmdutil.Owner, cmdutil.Repo
+	cmdutil.Owner = "Gitlink"
+	cmdutil.Repo = "gitlink-cli"
+	t.Cleanup(func() {
+		cmdutil.Owner = oldOwner
+		cmdutil.Repo = oldRepo
+	})
+
+	cmd := NewAPICmd()
+	if err := cmd.Flags().Set("var", "issue=42"); err != nil {
+		t.Fatalf("set var: %v", err)
+	}
+	headers := http.Header{"X-Issue": []string{"{{issue}}"}}
+	query := url.Values{
+		"repo": {"{{repo}}"},
+	}
+	body := map[string]interface{}{
+		"notes": "owner={{owner}} issue={{issue}}",
+	}
+
+	req, err := renderSingleAPIRequest("/:owner/:repo/issues/{{issue}}", query, body, headers, cmd)
+	if err != nil {
+		t.Fatalf("renderSingleAPIRequest error: %v", err)
+	}
+	if req.Path != "/Gitlink/gitlink-cli/issues/42" {
+		t.Fatalf("Path = %q", req.Path)
+	}
+	if req.Query.Get("repo") != "gitlink-cli" {
+		t.Fatalf("query repo = %q", req.Query.Get("repo"))
+	}
+	if req.Headers.Get("X-Issue") != "42" {
+		t.Fatalf("X-Issue = %q", req.Headers.Get("X-Issue"))
+	}
+	if !reflect.DeepEqual(req.Body, map[string]interface{}{"notes": "owner=Gitlink issue=42"}) {
+		t.Fatalf("Body = %#v", req.Body)
+	}
+}
+
+func TestParseAPIHeadersRejectsInvalidInput(t *testing.T) {
+	cmd := NewAPICmd()
+	if err := cmd.Flags().Set("header", "broken"); err != nil {
+		t.Fatalf("set header: %v", err)
+	}
+	if _, err := parseAPIHeaders(cmd); err == nil {
+		t.Fatal("expected invalid header error")
+	}
+}
+
 func TestRenderBatchRequestsTemplateVars(t *testing.T) {
 	requests, err := renderBatchRequests([]batchRequest{
 		{

doc/changes/api-single-request-templates.md

@@ -0,0 +1,7 @@
+# Raw API 单次调用模板变量与请求头支持
+
+`gitlink-cli api` 的单次调用模式现在和批处理模式对齐了模板渲染能力，不再只能手写完整路径。现在可以直接在路径里使用 `/:owner/:repo`，也可以在 path、query、JSON body、header 中使用 `{{owner}}`、`{{repo}}` 和自定义 `{{var}}` 变量；其中 `owner` / `repo` 会优先读取 `--var`，否则自动复用全局 `--owner`、`--repo` 或当前仓库上下文。
+
+这次改动同时把原来声明但未实际生效的 `--header` 接上了。单次请求现在支持通过 `--header key:value` 传递一个或多个自定义请求头，header 名和值都可以参与模板渲染，适合调试网关、透传审计字段、补充实验性接口所需头信息。
+
+本次提交补充了路径占位符回归测试、query/body/header 联动渲染测试、非法 header 校验测试，以及自定义 header 真正发到服务端的行为验证。README 和 README.zh-CN 也同步加入了单次请求模板变量示例，方便维护者、脚本和 Agent 直接复用。

internal/client/client.go

@@ -42,6 +42,10 @@ func New() (*Client, error) {
 }
 
 func (c *Client) Do(method, path string, body interface{}, query url.Values) (*output.Envelope, error) {
+	return c.DoWithHeaders(method, path, body, query, nil)
+}
+
+func (c *Client) DoWithHeaders(method, path string, body interface{}, query url.Values, headers http.Header) (*output.Envelope, error) {
 	path = normalizeAPIPath(c.BaseURL, path)
 
 	// Append .json suffix if not already present (GitLink API convention)
@@ -78,6 +82,11 @@ func (c *Client) Do(method, path string, body interface{}, query url.Values) (*o
 	if err != nil {
 		return nil, err
 	}
+	for key, values := range headers {
+		for _, value := range values {
+			req.Header.Add(key, value)
+		}
+	}
 
 	if c.Debug {
 		fmt.Printf("→ %s %s\n", method, fullURL)