調用 XYCMS API

XYCMS API 是(shì) XYCMS 系統的(de)底層 API，包含了(le／liǎo) XYCMS 系統的(de)核心接口與對象，XYCMS 系統本身即是(shì)基于(yú) XYCMS API開發而(ér)來(lái)，NuGet 托管地(dì / de)址：https://www.nuget.org/packages/XYCMS (opens new window)。

XYCMS API 的(de)詳細參考手冊請訪問 XYCMS API 參考 章節。

在(zài)此，我們以(yǐ) XYCMS 評論插件 (opens new window)爲(wéi / wèi)例說(shuō)明在(zài)不(bù)同的(de)環境下如何調用 XYCMS API。

Startup 初始化

插件必須繼承 IPluginExtension 接口或者 IPluginConfigureServices、IPluginConfigure 等繼承自 IPluginExtension 接口的(de)接口。

我們通常使用 Startup.cs 文件作爲(wéi / wèi)插件的(de)入口，繼承以(yǐ)上(shàng)接口中的(de)一(yī / yì ／yí)個(gè)，表明此項目是(shì) XYCMS 系統插件。

例如 XYCMS 評論插件 (opens new window)項目的(de) Startup.cs 文件：

using Microsoft.Extensions.DependencyInjection;
using XYCMS.Comments.Abstractions;
using XYCMS.Comments.Core;
using XYCMS.Plugins;

namespace XYCMS.Comments
{
    public class Startup : IPluginConfigureServices
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddScoped<ISettingsRepository, SettingsRepository>();
            services.AddScoped<ICommentRepository, CommentRepository>();
            services.AddScoped<ICommentManager, CommentManager>();
        }
    }
}

可以(yǐ)看到(dào)在(zài) Startup 類繼承了(le／liǎo) IPluginConfigureServices 接口，并實現了(le／liǎo) IPluginConfigureServices 接口的(de) ConfigureServices 方法。

ConfigureServices 方法用于(yú)配置依賴注入以(yǐ)在(zài)運行時(shí)根據依賴關系創建對象，用途與 ASP.NET Core 中的(de) ConfigureServices 用途一(yī / yì ／yí)緻，可以(yǐ)參考 ASP.NET Core 依賴注入 (opens new window)。

在(zài)以(yǐ)上(shàng)示例中，我們注入了(le／liǎo) ISettingsRepository、ICommentRepository 數據庫操作接口以(yǐ)及 ICommentManager 評論服務接口。

插件 Repositories 數據庫操作

在(zài)數據庫操作代碼中調用 XYCMS API 請參考 數據庫操作。

插件 Services 服務

我們以(yǐ) XYCMS 評論插件 (opens new window)的(de) CommentManager 類爲(wéi / wèi)例，說(shuō)明如何在(zài)服務代碼中調用 XYCMS API。

using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using XYCMS.Comments.Abstractions;
using XYCMS.Comments.Models;
using XYCMS.Comments.Utils;
using XYCMS.Models;
using XYCMS.Repositories;
using XYCMS.Services;
using XYCMS.Utils;

namespace XYCMS.Comments.Core
{
    public class CommentManager : ICommentManager
    {
        public const string PluginId = "xycms.comments";
        public const string PermissionsManage = "comments_manage";
        public const string PermissionsSettings = "comments_settings";
        public const string PermissionsTemplates = "comments_templates";

        private readonly ICacheManager _cacheManager;
        private readonly IPathManager _pathManager;
        private readonly IPluginManager _pluginManager;
        private readonly ISmsManager _smsManager;
        private readonly IMailManager _mailManager;
        private readonly ISettingsRepository _settingsRepository;
        private readonly ITableStyleRepository _tableStyleRepository;
        private readonly IContentRepository _contentRepository;
        private readonly ICommentRepository _commentRepository;

        public CommentManager(ICacheManager cacheManager, IPathManager pathManager, IPluginManager pluginManager, ISmsManager smsManager, IMailManager mailManager, ITableStyleRepository tableStyleRepository, IContentRepository contentRepository, ISettingsRepository settingsRepository, ICommentRepository commentRepository)
        {
            _cacheManager = cacheManager;
            _pathManager = pathManager;
            _pluginManager = pluginManager;
            _smsManager = smsManager;
            _mailManager = mailManager;
            _tableStyleRepository = tableStyleRepository;
            _contentRepository = contentRepository;
            _settingsRepository = settingsRepository;
            _commentRepository = commentRepository;
        }

        ......

        public async Task DeleteAsync(int siteId)
        {
            if (siteId <= 0) return;

            var relatedIdentities = new List<int> {siteId};

            await _tableStyleRepository.DeleteAllAsync(CommentUtils.TableName, relatedIdentities);
            await _commentRepository.DeleteBySiteIdAsync(siteId);
            await _settingsRepository.DeleteAsync(siteId);
        }

        ......

        public string GetTemplateHtml(TemplateInfo templateInfo)
        {
            var directoryPath = GetTemplatesDirectoryPath();
            var htmlPath = PathUtils.Combine(directoryPath, templateInfo.Name, templateInfo.Main);
            return _pathManager.GetContentByFilePath(htmlPath);
        }

        ......
    }
}

可以(yǐ)看到(dào)，我們在(zài) CommentManager 類構造器中通過依賴注入引入了(le／liǎo) XYCMS API 中的(de) ICacheManager、IPathManager、IPluginManager、ISmsManager、IMailManager、ITableStyleRepository、IContentRepository 服務，同時(shí)我們引入在(zài)了(le／liǎo) Startup 類中注入的(de) ISettingsRepository 以(yǐ)及 ICommentRepository 數據庫操作接口。

我們在(zài) DeleteAsync 方法中調用了(le／liǎo) XYCMS API ITableStyleRepository 接口的(de) DeleteAllAsync 方法，在(zài) GetTemplateHtml 方法中調用了(le／liǎo) XYCMS API IPathManager 接口的(de) GetContentByFilePath 方法。

同時(shí)我們在(zài) GetTemplateHtml 方法中調用了(le／liǎo) XYCMS API 靜态類 PathUtils 的(de) Combine 方法。

插件 Web API 控制器

最後，我們以(yǐ) XYCMS 評論插件 (opens new window)的(de) CommentsController 類爲(wéi / wèi)例，說(shuō)明如何在(zài)Web API 控制器代碼中調用 XYCMS API。

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using XYCMS.Comments.Abstractions;
using XYCMS.Comments.Core;
using XYCMS.Comments.Models;
using XYCMS.Repositories;
using XYCMS.Services;

namespace XYCMS.Comments.Controllers
{
    [Route("api/comments")]
    public partial class CommentsController : ControllerBase
    {
        private readonly IAuthManager _authManager;
        private readonly IUserRepository _userRepository;
        private readonly ILogRepository _logRepository;
        private readonly ISiteRepository _siteRepository;
        private readonly ICommentManager _commentManager;
        private readonly ICommentRepository _commentRepository;

        public CommentsController(IAuthManager authManager, IUserRepository userRepository, ILogRepository logRepository, ISiteRepository siteRepository, ICommentManager commentManager, ICommentRepository commentRepository)
        {
            _authManager = authManager;
            _userRepository = userRepository;
            _logRepository = logRepository;
            _siteRepository = siteRepository;
            _commentManager = commentManager;
            _commentRepository = commentRepository;
        }

        ......

        [HttpGet, Route("")]
        public async Task<ActionResult<GetResult>> List([FromQuery] ListRequest request)
        {
            var settings = await _commentManager.GetSettingsAsync(request.SiteId);

            List<Comment> list = null;
            var total = 0;
            var pageSize = settings.PageSize;

            if (request.Page > 0)
            {
                List<Comment> items;
                (total, items) = await _commentRepository.GetCommentsAsync(request.SiteId, request.ChannelId, request.ContentId, CommentStatus.Approved, null, request.Page, pageSize);
                list = new List<Comment>();
                foreach (var item in items)
                {
                    var comment = item.Clone<Comment>();
                    var user = new User();
                    if (comment.UserId > 0)
                    {
                        user = await _userRepository.GetByUserIdAsync(comment.UserId);
                    }
                    comment.Set("user", user);
                    list.Add(comment);
                }
            }

            return new GetResult
            {
                IsSubmitDisabled = settings.IsSubmitDisabled,
                IsCaptcha = settings.IsCaptcha,
                IsApprovedByDefault = settings.IsApprovedByDefault,
                Items = list,
                Total = total,
                PageSize = pageSize
            };
        }

        [HttpPost, Route("")]
        public async Task<ActionResult<SubmitResult>> Submit([FromBody] Comment request)
        {
            var site = await _siteRepository.GetAsync(request.SiteId);
            var settings = await _commentManager.GetSettingsAsync(request.SiteId);
            if (settings.IsSubmitDisabled)
            {
                return this.Error("對不(bù)起，評論已被禁用");
            }

            request.UserId = _authManager.UserId;
            request.Status = settings.IsApprovedByDefault ? CommentStatus.Approved : CommentStatus.Pending;
            request.IpAddress = PageUtils.GetIpAddress(Request);

            request.Id = await _commentRepository.InsertAsync(request);
            await _commentManager.SendNotifyAsync(site, settings, request);

            List<Comment> list = null;
            var total = 0;
            if (settings.IsApprovedByDefault)
            {
                List<Comment> items;
                (total, items) = await _commentRepository.GetCommentsAsync(request.SiteId, request.ChannelId, request.ContentId, CommentStatus.Approved, null, 1, settings.PageSize);
                list = new List<Comment>();
                foreach (var item in items)
                {
                    var comment = item.Clone<Comment>();
                    var user = new User();
                    if (comment.UserId > 0)
                    {
                        user = await _userRepository.GetByUserIdAsync(comment.UserId);
                    }
                    comment.Set("user", user);
                    list.Add(comment);
                }
            }

            if (_authManager.IsUser)
            {
                var user = await _authManager.GetUserAsync();
                await _logRepository.AddUserLogAsync(user, PageUtils.GetIpAddress(Request), "發表評論");
            }

            return new SubmitResult
            {
                Items = list,
                Total = total
            };
        }
    }
}

可以(yǐ)看到(dào)，我們在(zài) CommentsController 類構造器中通過依賴注入引入了(le／liǎo) XYCMS API 中的(de) IAuthManager、IUserRepository、ILogRepository、ISiteRepository 服務，同時(shí)我們引入在(zài)了(le／liǎo) Startup 類中注入的(de) ICommentManager 服務接口以(yǐ)及 ICommentRepository 數據庫操作接口。

我們在(zài) List 方法中調用了(le／liǎo) XYCMS API IUserRepository 接口的(de) GetByUserIdAsync 方法，在(zài) Submit 方法中調用了(le／liǎo) XYCMS API ISiteRepository 接口的(de) GetAsync 方法等。