// 获取我点赞的帖子
//
//	@Summary	获取我点赞的帖子
//	@Tags		likes
//	@Security	BearerAuth
//	@Param		page		query		int		false	"页码"		default(1)
//	@Param		page_size	query		int		false	"每页数量"	default(20)
//	@Success	200			{object}	render.Response[pageResponse[listPostsItemResponse]]
//	@Failure	500			{object}	render.errorResponse
//	@Router		/me/likes [get]
func (h *LikeHandler) ListLikedPosts(w http.ResponseWriter, r *http.Request) {
	// ...
}

swag init -d internal/api,internal/pkg/render -g routes.go --parseInternal --v3.1 -ot yaml

import { defineConfig } from "orval";

export default defineConfig({
  bluebook: {
    input: {
      target: "./swagger.yaml", // 接口契约规范来源
    },
    output: {
      mode: "tags-split", // 按 @Tags 划分模块文件
      target: "src/api", // 输出生成目录
      client: "react-query", // 生成 TanStack Query Hooks
      httpClient: "axios", // 底层 HTTP 客户端
      formatter: "oxfmt", // 使用 oxfmt 进行输出排版
      override: {
        mutator: {
          path: "./src/mutator.ts", // 注入自定义 Axios 请求实例
          name: "customInstance",
        },
      },
    },
  },
});

/**
 * Generated by orval 🍺
 * Do not edit manually.
 */

// 1. 强类型请求函数, 参数与返回值均具备类型推导
export const getPostsPostId = (postId: string, options?: SecondParameter<typeof customInstance>, signal?: AbortSignal) => {
  return customInstance<RenderResponseApiGetPostsResponse>(
    { url: `/posts/${postId}`, method: "GET", signal },
    options,
  );
};

// 2. QueryKey 生成器, 保障缓存清理的类型确定性
export const getGetPostsPostIdQueryKey = (postId: string) => {
  return [`/posts/${postId}`] as const;
};

// 3. 内置 TanStack Query Hook, 在组件内直接使用
export function useGetPostsPostId<TData, TError = RenderErrorResponse>(...) { ... }

// 统一返回包装规范示例
{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

import Axios, {
  AxiosError,
  type AxiosRequestConfig,
  type AxiosResponse,
  type InternalAxiosRequestConfig,
} from "axios";

import { postAuthRefresh } from "@/api/auth/auth";

type ApiResponse = { code: number; msg: string; data?: unknown };
type RetriableRequestConfig = InternalAxiosRequestConfig & { _retriedAfterRefresh?: boolean };

const ACCESS_TOKEN_KEY = "access_token";
const REFRESH_TOKEN_KEY = "refresh_token";
const ME_KEY = "blue_book:me";
const UNAUTHENTICATED_AUTH_ENDPOINTS = new Set(["/auth/login", "/auth/register", "/auth/refresh"]);

export class ApiError extends Error {
  code: number;
  msg: string;
  data?: unknown;

  constructor(msg: string, code: number, data?: unknown) {
    super(msg);
    this.name = "ApiError";
    this.code = code;
    this.msg = msg;
    this.data = data;
  }
}

type ApiPayload<T> = T extends { data?: infer TData } ? TData : void;

export const AXIOS_INSTANCE = Axios.create({
  baseURL: "/api/v1",
});

function isUnauthenticatedAuthEndpoint(url?: string) {
  return UNAUTHENTICATED_AUTH_ENDPOINTS.has(url ?? "");
}

AXIOS_INSTANCE.interceptors.request.use((config) => {
  const token = localStorage.getItem(ACCESS_TOKEN_KEY);
  if (token && config.headers && !isUnauthenticatedAuthEndpoint(config.url)) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

let refreshPromise: Promise<string> | undefined;

function clearSession() {
  localStorage.removeItem(ACCESS_TOKEN_KEY);
  localStorage.removeItem(REFRESH_TOKEN_KEY);
  localStorage.removeItem(ME_KEY);
  window.dispatchEvent(new Event("blue_book:session-expired"));
}

async function refreshAccessToken() {
  const refreshToken = localStorage.getItem(REFRESH_TOKEN_KEY);
  if (!refreshToken) throw new ApiError("登录已过期,请重新登录", 401);

  const auth = await postAuthRefresh({ refresh_token: refreshToken });
  if (!auth.access_token) throw new ApiError("登录凭证刷新失败", 401);

  localStorage.setItem(ACCESS_TOKEN_KEY, auth.access_token);
  if (auth.refresh_token) localStorage.setItem(REFRESH_TOKEN_KEY, auth.refresh_token);
  return auth.access_token;
}

async function retryAfterRefresh(config: RetriableRequestConfig) {
  if (config._retriedAfterRefresh || isUnauthenticatedAuthEndpoint(config.url)) {
    throw new ApiError("登录已过期,请重新登录", 401);
  }
  try {
    refreshPromise ??= refreshAccessToken().finally(() => {
      refreshPromise = undefined;
    });
    const token = await refreshPromise;
    config._retriedAfterRefresh = true;
    config.headers.Authorization = `Bearer ${token}`;
    return AXIOS_INSTANCE(config);
  } catch {
    clearSession();
    throw new ApiError("登录已过期,请重新登录", 401);
  }
}

// 统一响应与状态拦截
AXIOS_INSTANCE.interceptors.response.use(
  async (response: AxiosResponse<ApiResponse>) => {
    const { code, msg, data } = response.data;
    if (code < 200 || code >= 300) {
      const apiError = new ApiError(msg, code, data);
      if (code === 401) return retryAfterRefresh(response.config as RetriableRequestConfig);
      throw apiError;
    }
    return response;
  },
  async (error: AxiosError<ApiResponse>) => {
    if (error.response?.data) {
      const { code, msg, data } = error.response.data;
      if (code === 401 || error.response.status === 401) {
        return retryAfterRefresh(error.config as RetriableRequestConfig);
      }
      throw new ApiError(msg, code, data);
    }
    throw error;
  },
);

export const customInstance = <T>(
  config: AxiosRequestConfig | string,
  options?: AxiosRequestConfig,
): Promise<ApiPayload<T>> => {
  const requestConfig: AxiosRequestConfig =
    typeof config === "string" ? { url: config, ...options } : { ...config, ...options };
  return AXIOS_INSTANCE(requestConfig).then(({ data }) => data.data as ApiPayload<T>);
};

export default customInstance;

import {
  useDeletePostsPostIdLike,
  useGetPostsPostId,
  usePutPostsPostIdLike,
} from "@/api/posts/posts";
import { ApiError } from "@/mutator";

const postQuery = useGetPostsPostId(postId);
const likeMutation = usePutPostsPostIdLike();
const unlikeMutation = useDeletePostsPostIdLike();
const post = postQuery.data;

const handleLike = async () => {
  if (!post) return;
  try {
    if (!post.viewer_liked) await likeMutation.mutateAsync({ postId });
    else await unlikeMutation.mutateAsync({ postId });
  } catch (err) {
    if (err instanceof ApiError) toast.error(err.msg);
  }
};

# 后端重新导出契约
make swagger
# 前端依据新契约生成 SDK 并执行类型检查
pnpm gen:api && pnpm build

src/routes/PostDetailPage.tsx:87:30: error TS2339: Property 'like_count' does not exist on type 'RenderResponseApiGetPostsResponse'. Did you mean 'count'?

- <span>{post.like_count} 点赞</span>
+ <span>{post.count} 点赞</span>

{
  "scripts": {
    "gen:api": "orval"
  }
}

### 前端 API 使用规范
1. `swagger.yaml` 是接口定义的唯一来源;运行 `pnpm gen:api` 重新生成 `src/api`。
2. 严禁手动修改或新增 `src/api` 目录下的任何文件,其归属自动化工具生成。
3. 所有数据请求必须调用 `src/api` 中生成的方法,禁止在组件中直接手写 `fetch` 或重复声明响应类型。
4. 请求异常优先展示 `ApiError.msg`。

### 后端接口规范
1. 接口注解或响应类型变更后,必须执行 `make swagger` 重新生成 `docs/swagger.yaml`。
2. 注解统一使用泛型 `render.Response[T]`,保持 `@Success` 注释格式规范,避免声明松散的无类型结构。

79.65%  regexp.(*Regexp).tryBacktrack
97.27%  regexp.(*Regexp).backtrack

### 增量性能重构协作协议
1. **依据数据下钻,拒绝全局猜测**: 性能重构请求必须附带两项基准事实:
   - 包含累积耗时 cum 排行的性能分析报告或代码行分析记录;
   - 现存的微基准测试代码。
2. **严格锁定契约**: 重构前必须存在完备的表驱动单元测试;严禁修改导出函数的签名与返回值语义。
3. **针对底层瓶颈迭代重构**:
   - CPU 计算: 检查全量快速排序是否可收敛为固定大小堆、固定格式替换是否能脱离正则引擎、多变量渲染是否可合并为单次遍历状态机;
   - I/O 路径: 检查是否存在小数据块密集系统调用,强制采用页面对齐的用户态缓冲合并;目录遍历优先选用目录条目复用函数;
   - 锁竞争路径: 在读多写少场景,使用基于写时复制的无锁架构替代读写锁;高频并发读写必须做哈希分片;
   - 内存路径: 检查截取存入长生命周期的子切片,强制执行深拷贝切断底层大数组引用;对象池严禁直接存值类型切片避免接口装箱逃逸;大批量结构体必须紧凑排布消除填充。
4. **增量闭环验证**: 交付的代码必须通过微基准测试验证单轮优化收益,并顺着新的累积耗时排行推进下一轮重构。

无状态纯计算 ──→ 表驱动单元测试: 确定性输入映射确定性输出 (毫秒级响应)
业务状态流转 ──→ 真实容器集成测试: 加载真实数据库引擎, 执行原生迁移文件 (引擎直接裁决)
并发与时钟   ──→ testing/synctest: 虚拟时钟 bubble 与受控协程调度 (消除 Flaky)

func Score(likes, comments int, age time.Duration) int {
	penalty := int(age.Hours() / 24)
	return max(likes+comments*2-penalty, 0)
}

func TestScore(t *testing.T) {
	tests := []struct {
		name            string
		likes, comments int
		age             time.Duration
		want            int
	}{
		{name: "新帖子", likes: 10, comments: 3, want: 16},
		{name: "一天后衰减", likes: 10, comments: 3, age: 24 * time.Hour, want: 15},
		{name: "最低为零", age: 30 * 24 * time.Hour, want: 0},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := Score(tt.likes, tt.comments, tt.age); got != tt.want {
				t.Fatalf("Score() = %d, want %d", got, tt.want)
			}
		})
	}
}

package testutil

import (
	"testing"

	"github.com/jackc/pgx/v5/pgxpool"
	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/modules/postgres"

	"your/project/internal/migrations"
)

func Postgres(t *testing.T) *pgxpool.Pool {
	t.Helper()
	if testing.Short() {
		t.Skip("skipping integration test in short mode")
	}

	ctx := t.Context()
	container, err := postgres.Run(ctx,
		"postgres:18-alpine",
		postgres.WithDatabase("app_test"),
		postgres.WithUsername("app"),
		postgres.WithPassword("app"),
		postgres.BasicWaitStrategies(),
	)
	if err != nil {
		t.Fatalf("start postgres: %v", err)
	}
	testcontainers.CleanupContainer(t, container)

	dsn, err := container.ConnectionString(ctx, "sslmode=disable")
	if err != nil {
		t.Fatalf("postgres connection string: %v", err)
	}

	db, err := pgxpool.New(ctx, dsn)
	if err != nil {
		t.Fatalf("connect postgres: %v", err)
	}
	t.Cleanup(db.Close)

	if err := migrations.Up(ctx, db); err != nil {
		t.Fatalf("run migrations: %v", err)
	}
	return db
}

func TestLikePostIsIdempotent(t *testing.T) {
	db := testutil.Postgres(t)
	ctx := t.Context()

	if _, err := db.Exec(ctx,
		`INSERT INTO users (id, name) VALUES ($1, $2)`, 1, "sanbei",
	); err != nil {
		t.Fatal(err)
	}
	if _, err := db.Exec(ctx,
		`INSERT INTO posts (id, user_id, content) VALUES ($1, $2, $3)`, 100, 1, "hello",
	); err != nil {
		t.Fatal(err)
	}

	service := NewLikeService(NewPostgresLikeRepository(db))
	if err := service.Like(ctx, 1, 100); err != nil {
		t.Fatal(err)
	}
	if err := service.Like(ctx, 1, 100); err != nil {
		t.Fatalf("second Like() should be idempotent: %v", err)
	}

	var likes int
	if err := db.QueryRow(ctx,
		`SELECT count(*) FROM post_likes WHERE user_id = $1 AND post_id = $2`, 1, 100,
	).Scan(&likes); err != nil {
		t.Fatal(err)
	}
	if likes != 1 {
		t.Fatalf("like rows = %d, want 1", likes)
	}
}

var ErrModerationTimeout = errors.New("moderation timeout")

type ModerationResult struct {
	Approved bool
	Reason   string
}

func AwaitModeration(ctx context.Context, result <-chan ModerationResult) (ModerationResult, error) {
	timer := time.NewTimer(3 * time.Second)
	defer timer.Stop()

	select {
	case <-ctx.Done():
		return ModerationResult{}, ctx.Err()
	case r := <-result:
		return r, nil
	case <-timer.C:
		return ModerationResult{}, ErrModerationTimeout
	}
}

func TestAwaitModerationTimeout(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		result := make(chan ModerationResult)
		done := make(chan error, 1)
		go func() {
			_, err := AwaitModeration(t.Context(), result)
			done <- err
		}()

		// 推进至距截止时间仅剩 1ns, 此时不可提前触发超时
		synctest.Sleep(3*time.Second - time.Nanosecond)
		select {
		case err := <-done:
			t.Fatalf("returned before deadline: %v", err)
		default:
		}

		// 再推进 1ns 跨越边界, 此时必须触发超时
		synctest.Sleep(time.Nanosecond)
		if err := <-done; !errors.Is(err, ErrModerationTimeout) {
			t.Fatalf("AwaitModeration() error = %v, want %v", err, ErrModerationTimeout)
		}
	})
}