قسمت پیشنهادها، مرتبط با ارائه نظر نیست؛ مرتبط با ارائه ایده برای تهیه مطلب هست. نمونه‌های قبلی آن برای بررسی موجود هستند. برای دسترسی به آن هم باید حداقل 2 اشتراک/لینک ارسالی داشته باشید.

من تجربه استفاده ترکیبی از C4 Model برای نمایش بصری معماری سیستم در چندین سطح مختلف را به همراه قالب خوش فرم MADR (Markdown Any Decision Records) را داشتم. در نسخه های قبلی MADR برای مستند سازی تصمیمات معماری استفاده می شد که بعد از نسخه ۳ برای ثبت و ضبط تمام تصمیمات تاثیرگذار در طراحی سیستم می توان استفاده کرد. این موارد در کنار مستندات OpenAPI Spec که امین جان عنوان کردند، در کنار سورس کد برنامه در پوشه docs نگهداری می شوند.

علاوه بر موارد مطرح شده، استفاده از Gherkin برای نوشتن سناریوهای تست نیز می تواند به عنوان ابزار خوبی برای مستندسازی رفتار سیستم باشد؛ به طوری که با زبان مختص دامین مورد نظر رفتار سیستم را شرح داده است.

مستندات فنی که اصطلاحاً به صورت high-level هستند و خیلی به صورت مداوم به‌روز نمیشن رو شاید بهتر باشه خارج از سورس‌کد ذخیره کرد. روالی که من توی تیم‌ها میبینم اینطور بوده که یک ساختار این مدلی داشتن:

• Archives
• Technical
  • ADRs
  • Architetures
  • QA
  • UX Researches
• Meetings
• Releases

برای مستندات فنی‌تر هم همونطور که اشاره کردید توی پوشه docs/ به صورت markdown قرار میگیرن؛ نکته مهمی که دسترسی رو برای همه ساده‌تر میکنه داشتن یک فایل ایندکس (markdown) هست.

در نهایت میتونید همه رو داخل همون پوشه docs/ قرار بدید و به صورت قابل دیپلوی در دسترس بقیه اعضای تیم قرار بدید (میتونه بخشی از فرآیند CI/CD باشه مثلاً به محض مرج شدن یک فیچر در برنچ اصلی محتویات پوشه docs/ هم دیپلوی بشه) ابزارهای زیادی هم برای اینکار استفاده میشن مثلاً میتونید از Docusaurus برای اینکار استفاده کنید:

استاندارد خیر. ولی best practice هایی وجود داره.

و خیلی خیلی بستگی به سایزسازمان و تیم، ساختار تیم و روش توسعه، و عمق مستنداتی که تولید می‌کنید داره، مثال: گاهی یک تیم بزرگ تصمیم می‌گیره از ابزار wiki موجود در Gitlab, GitHub, Azure DevOps استفاده کنه (همون‌جایی که سورس کد قرار داره، ولی در بخش ویکی) یا در کانفلوئنس (اگر داشته باشن)

گاهی در فایل README.md در root پروژه به شکل قراردادی مشخصات ذکر می‌شه.

گاهی فایل‌های markdown در پوشه docs در سورس‌کد

گاهی شما نیاز به معرفی REST API دارید که OpenAPI Spec کمک می‌کنه

گاهی دیاگرام هم نیاز دارید برای یک سیستم بزرگ‌تر

گاهی فقط وابستگی‌ها مثل پکیج‌ها براتون مهمه، که فایل .packages.props کمک میاد

تجربه شخصی من، نسبت به هر تیم و شرکتی متناسب با همون تصمیم گرفتم (از فایل README.MD تا مدخل در ویکی که بعد از مدتی به چندصد صفحه تبدیل شده که چندین نفر به تدریج کاملش کردند)

کتابخانه «DNTCommon.Web.Core» به همراه روشی چندسکویی برای دریافت اطلاعات سرور هم هست. پس از دریافت اطلاعات، فقط کافی است یک AuthorizationFilter سفارشی را برای بررسی آن طراحی کنید:

public class RestrictServerAttribute : Attribute, IAuthorizationFilter
{
    public void OnAuthorization(AuthorizationFilterContext context)
    {
        if (/* check server info */)
        {
            //  Request came from an unauthorized host, return bad request
            context.Result = new BadRequestObjectResult("Host is not allowed");
        }
    }
}

و سپس آن‌را به صورت یک فیلتر سراسری معرفی کنید تا به همه‌جا اعمال شود:

public void ConfigureServices(IServiceCollection services)
{
   services.AddControllers(options =>
        {
            options.Filters.Add(new RestrictServerAttribute());
        });
}

گویا نیازی به تعریف ستون ها نیست (تازه متوجه شدم) و به روش زیر هم میشه ساده انجام بشه:

public class JoitnProfile : Profile
{
    public JoitnProfile()
    {
        CreateMap<LineJoint, Models.Output.Piping.LineJoints.LineJoint2>();
    }
}

و استفاده از ConfigurationProvider پیش فرض:

var result = await query.ProjectTo<Models.Output.Piping.LineJoints.LineJoint2>(_mapper.ConfigurationProvider).ToListAsync();

پروژه Selector تعطیل و AutoMapper جایگزین میکنم. تشکر جناب نصیری

ضمن تشکر. جهت یادگیری میپرسم. اگرچه که AutoMapper میتونه مشکل را حل کنه ولی تمام ستون های مورد نیازم رو باید در configuration تعریف کنم. آیا اگر خودم بتونم یک Selector مانند نمونه زیر ایجاد کنم بهتر نیست؟ دلیل این کار کاهش وابستگی و راندمان بیشتره. آیا ایجاد Selectorی مانند زیر این دو هدف را برآورده میکنه؟

private static Expression<Func<LineJoint, Models.Output.Piping.LineJoints.LineJoint2>> Selector()
{
    //if (Condition())
    //    return x => new Models.Output.Piping.LineJoints.LineJoint2
    //    {
    //        ....
    //    };

    return x => new Models.Output.Piping.LineJoints.LineJoint2
    {
        Id = x.Id,
        JointNo = x.JointNo
    };
}

در نتیجه میتونم query را بصورت زیر اجرا کنم:

var result = await query.Select(Selector()).ToListAsync();

قبلا مطلبی رو در مورد توانایی AutoMapper در تهیه‌ی یک چنین نگاشت‌هایی با استفاده از متد project to آن، تهیه کردم. البته کلیاتش فرقی نکرده؛ ولی syntax اش تغییر کرده که آخرین به روز رسانی اون رو در اینجا می‌تونید مطالعه کنید. به‌شما توصیه می‌کنم از همین روش استفاده کنید و سعی نکنید این متد رو خودتون بازنویسی کنید و بهتر از است از همان نمونه‌‌ای که سال‌هاست آزمایش شده و در حال استفاده‌است، کمک بگیرید.

return context.OrderLines.Where(ol => ol.OrderId == orderId)
             .ProjectTo<OrderLineDTO>(configuration).ToList();

البته یک نمونه در اینترنت پیدا کردم (البته پاسخ Copilot بوده) که متد را بصورت Generic تعریف کرده بود که برای انجام Dynamic Select روش زیر را بکاربرده بود:

IQueryable<TResult> results = query.SelectMany(x => selectProperties.Select(prop => prop.Compile()(x)));

تا اینجا هیچ مشکلی وجود ندارد ولی به محض آنکه در خط بعدی متد ToList اجرا میشه با پیغام خطا مواجه میشم:

An exception was thrown while attempting to evaluate a LINQ query parameter expression. See the inner exception for more information. To show additional information call 'DbContextOptionsBuilder.EnableSensitiveDataLogging'.

کد کامل Copilot:

public async Task<List<LineJoint2>> GetAsync2(
    Expression<Func<LineJoint, bool>> filter,
    List<Expression<Func<LineJoint, object>>> includes,
    List<Func<IIncludableQueryable<LineJoint, object>, IIncludableQueryable<LineJoint, object>>> thenIncludes,
    Expression<Func<IQueryable<LineJoint>, IOrderedQueryable<LineJoint>>> orderBy,
    int pageSize,
    int pageNumber,
    bool trackChanges = true,
    CancellationToken cancellationToken = default)
{
    var query = context.LineJoints.AsQueryable();

    // Apply filter
    if (filter != null)
        query = query.Where(filter);

    // Include related entities
    foreach (var include in includes)
        query = query.Include(include);

    // Apply thenIncludes
    foreach (var thenInclude in thenIncludes)
        query = thenInclude(query);

    // Project properties dynamically
    var projectedQuery = query.Select(x => new LineJoint2
    {
        Id = x.Id,
        JointNo = x.JointNo
        // Add other properties from LineJoint as needed
    });

    // Apply ordering
    if (orderBy != null)
        projectedQuery = orderBy.Compile()(projectedQuery);

    // Apply pagination
    var pagedQuery = projectedQuery.Skip((pageNumber - 1) * pageSize).Take(pageSize);

    // Execute the query
    return await (trackChanges ? pagedQuery : pagedQuery.AsNoTracking()).ToListAsync(cancellationToken);
}

الزاما نیازی نیست که از Redis استفاده کنید؛ چون Distributed Memory Cache هم داریم (^):

builder.Services.AddDistributedMemoryCache();