Makalalar toparyna ýazylmak mümkinçiligini goşýarys. (1-nji bölüm) - "A-dan Z-a çenli Java taslamasy"

Salam! Bu gün JavaRush-daky makalalar toparyna abunalyk goşarys. Bu GitHub-da JRTB-5 çykarylyşyna gabat gelýär . Düşündireýin: JavaRush-da Makalalar atly bölüm bar we içinde Makalalar topary bar. Bu pikir, telegramma botynyň üsti bilen bir ýa-da birnäçe topardan täze makala barada habarnamalary almak.

JRTB-5 goşuň

Üstünlik hekaýalary toparynyň makalalary meni gyzyklandyrýar diýeliň . Şonuň üçin bu toparyň täzelenmelerine ýazylmak we her gezek täze neşire baglanyşyk almak isleýärin. Bu meseläniň bir bölegi hökmünde, JavaRush-da toparlar bilen işlemek üçin açyk API-ni nähili ulanmalydygyny öwrenmeli. Edil şu wagt şeýle zat geldi. Ine, açyk API-iň beýanyna baglanyşyk .

Swagger näme? Geliň indi düşüneliň

Swagger hakda entek gürleşmedik. Bilmeýänler üçin gysgaça düşündirerin: bu serweriň API-sine aç-açan seredip, oňa käbir haýyşlar edip bilersiňiz. Adatça, aldawçy toparlar mümkin islegleri. Biziň ýagdaýymyzda üç topar bar: forum-sorag , topar , ýazgy . Her toparda bu haýyşy gurmak üçin zerur maglumatlary görkezýän bir ýa-da birnäçe haýyş bolar (ýagny haýsy goşmaça parametrleri geçirip bolar, olar bilen näme etmeli, haýsy http usuly we ş.m.). Bu mowzukda has köp okamagyňyzy we tomaşa etmegiňizi maslahat berýärin, sebäbi bu ösüşiň her biriňiziň diýen ýaly duşjak bölegi. Muny anyklamak üçin, JavaRush-da näçe toparyň bardygyny bileliň. Munuň üçin topar-gözegçilik toparyny giňeldiň we Get request /api/1.0/rest/groups/count saýlaň . JavaRush-da toparlaryň sanyny bize gaýtaryp berer. Geliň seredeliň: Surat bu talapyň birnäçe parametrleri (talap, görnüş, süzgüç) goldaýandygyny görkezýär. Bu haýyşy synap görmek üçin “Synap görüň” düwmesini tapmaly , şondan soň bu parametrler düzülip bilner: Şeýle hem görnüşini, süzgüçini we soragyny sazlap bilersiňiz (aslynda bu ýerde gyzykly: bu tekstde gözleg bolar) topar). Nowöne häzirlikçe hiç hili çäklendirmesiz işledeliň we JavaRush-da näçe toparyň bardygyny göreliň. Munuň üçin “Execute” -e basyň. Aşakda bu haýyşa jogap bolar (Serweriň jogap bölüminde): Jemi 30 toparyň bardygyny görýäris , bu haýyş 95 metrde tamamlandy we jogapda käbir sözbaşylar bar. Indiki, käbir parametrleri düzmäge synanyşalyň. KOMPANI valueA bahasyna deň bolan görnüş parametrini saýlalyň we netijäniň nähili üýtgeýändigini göreliň: Olardan 4-si bar. Muny nädip barlamaly? Bu aňsat: web sahypasyna girip, makala bölümini tapyp, ähli toparlary saýlap we degişli filtri goşup bilersiňiz ( https://javarush.com/groups/all?type=COMPANY ). Hawa, hakykatdanam, olardan diňe 4-si bar. Aslynda üçüsi bar: D Şu wagta çenli gabat gelýär. Theeri gelende aýtsak, uniwersitetleri barlasak, entek ýok. Diňe hezil etmek üçin, Javarush-a giren we girmedik brauzeriňizde süzgüç = MEN goýsaňyz näme bolýandygyny görüň. Aldawçy hakda has giňişleýin - Habre hakda şu makalada .

Toparlar üçin Javarush API üçin müşderi ýazmak

Indi açyk API-e esaslanyp, haýyşlar edip bilýän, jogap alyp bilýän we haýsy obýektleriň geljekdigini anyk bilýän Java müşderisini ýazarys. Şeýle hem, swaggerden, Modeller bölüminden (sahypanyň iň aşagyndaky) zatlary alarys . Geliň, täze paket döredeliň we hyzmatyň, ammaryň gapdalynda javarushclient diýeliň. Geljekde muny Javarush jemgyýetçilik guramasynyň çäginde aýratyn kitaphana göçüreris we diňe garaşlylyk hökmünde ulanarys. Ilki bilen JavaRush API-de http haýyşlaryny döretmek üçin kitaphana bolan “Unitrest” -i goşmaly:

<dependency>
  <groupId>com.konghq</groupId>
  <artifactId>unirest-java</artifactId>
  <version>${unirest.version}</version>
</dependency>

Wersiýasyny häsiýetler blokyna salyň:

<unirest.version>3.11.01</unirest.version>

Garaşly bolanymyzdan soň kod goşup bileris. JavaRushGroupClient toparlary üçin müşderi döredeliň we JavaRushGroupClientImpl synpynda durmuşa geçireliň. Firstöne ilki bilen DTO-lary (maglumatlary geçirmek obýektleri) döretmeli, ýagny obýektleri müşderi üçin zerur bolan ähli maglumatlary göterjek synplary döretmeli. Modelshli modelleri swaggerde görüp bolýar. Iň aşaky böleginde Modeller bölümi bar , olary sanap bilersiňiz. “GroupDiscussionInfo” swaggerdäki ýaly görünýär: “ Javarushclient” bukjasynda, dto paketini dörederis , swagger-iň maglumatlaryna esaslanyp, aşakdaky synplar goşarys:

• MeGroupInfoStatus :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  /**
  * Member group status.
  */
  public enum MeGroupInfoStatus {
     UNKNOWN, CANDIDATE, INVITEE, MEMBER, EDITOR, MODERATOR, ADMINISTRATOR, BANNED
  }

• MeGroupInfo :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  import lombok.Data;
  
  /**
  * Group information related to authorized user. If there is no user - will be null.
  */
  @Data
  public class MeGroupInfo {
     private MeGroupInfoStatus status;
     private Integer userGroupId;
  }

• GroupInfoType :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  /**
  * Group Info type;
  */
  public enum GroupInfoType {
     UNKNOWN, CITY, COMPANY, COLLEGE, TECH, SPECIAL, COUNTRY
  }

• UlanyjyDiskussionInfo :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  import lombok.Data;
  
  /**
  * DTO for User discussion info.
  */
  @Data
  public class UserDiscussionInfo {
  
     private Boolean isBookmarked;
     private Integer lastTime;
     private Integer newCommentsCount;
  }

• GroupVisibilitysdtatus :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  /**
  * Group Visibility status.
  */
  public enum GroupVisibilityStatus {
     UNKNOWN, RESTRICTED, PUBLIC, PROTECTED, PRIVATE, DISABLED, DELETED
  }

• Soňra - GroupInfo :

  package com.github.javarushcommunity.jrtb.javarushclient.dto;
  
  import lombok.Data;
  import lombok.ToString;
  
  /**
  * Group Info DTO class.
  */
  @Data
  @ToString
  public class GroupInfo {
  
     private Integer id;
     private String avatarUrl;
     private String createTime;
     private String description;
     private String key;
     private Integer levelToEditor;
     private MeGroupInfo meGroupInfo;
     private String pictureUrl;
     private String title;
     private GroupInfoType type;
     private Integer userCount;
     private GroupVisibilityStatus visibilityStatus;
  }

GroupInfo we GroupDiscussionInfo düýbünden birmeňzeş bolansoň, geliň olary miras bilen baglanyşdyralyň - GroupDiscusionInfo :

package com.github.javarushcommunity.jrtb.javarushclient.dto;

import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.ToString;

/**
* Group discussion info class.
*/
@EqualsAndHashCode(callSuper = true)
@Data
@ToString(callSuper = true)
public class GroupDiscussionInfo extends GroupInfo {

   private UserDiscussionInfo userDiscussionInfo;
   private Integer commentsCount;
}

Şeýle hem, GroupFilter haýyşy üçin süzgüç gerek bolar :

package com.github.javarushcommunity.jrtb.javarushclient.dto;

/**
* Filters for group requests.
*/
public enum GroupFilter {

   UNKNOWN, MY, ALL
}

Şahsyýetnama bilen almak haýyşynda, GroupDiscussionInfo-y yzyna gaýtarýar we toparlary ýygnamak haýyşynda GroupInfo we GroupDiscussionInfo-ny alyp bilersiňiz. Islegleriň görnüşi, talaplary, süzgüçleri, ofsetleri we çäkleri bolup bilýändigi sebäpli, aýratyn GroupRequestArgs synpyny döredeliň we ony gurluşykçy synpyna öwüreliň (gurluşykçynyň nagşynyň nämedigini okaň):

package com.github.javarushcommunity.jrtb.javarushclient.dto;

import lombok.*;

import java.util.HashMap;
import java.util.Map;

import static java.util.Objects.nonNull;

/**
* Request arguments for group requests.
*/
@Builder
@Getter
public class GroupRequestArgs {

   private final String query;
   private final GroupInfoType type;
   private final GroupFilter filter;

   /**
    * specified where to start getting groups
    */
   private final Integer offset;
   /**
    * Limited number of groups.
    */
   private final Integer limit;

   public Map populateQueries() {
       Map queries = new HashMap<>();
       if(nonNull(query)) {
           queries.put("query", query);
       }
       if(nonNull(type)) {
           queries.put("type", type);
       }
       if(nonNull(filter)) {
           queries.put("filter", filter);
       }
       if(nonNull(offset)) {
           queries.put("offset", offset);
       }
       if(nonNull(limit)) {
           queries.put("limit", limit);
       }
       return queries;
   }
}

Toparlaryň sanyny gözlemek üçin birneme üýtgeşik. Diňe talap, görnüş we süzgüç bar. Kody köpeltmek islemeýän ýaly. Şol bir wagtyň özünde, olary birleşdirip başlasaňyz, gurluşykçylar bilen işleşende erbet bolýar. Şonuň üçin olary bölüp, kody gaýtalamagy makul bildim. “GroupCountRequestArgs” -iň görnüşi :

package com.github.javarushcommunity.jrtb.javarushclient.dto;

import lombok.Builder;
import lombok.Getter;

import java.util.HashMap;
import java.util.Map;

import static java.util.Objects.nonNull;

/**
* Request arguments for group count requests.
*/
@Builder
@Getter
public class GroupsCountRequestArgs {
   private final String query;
   private final GroupInfoType type;
   private final GroupFilter filter;

   public Map populateQueries() {
       Map queries = new HashMap<>();
       if (nonNull(query)) {
           queries.put("query", query);
       }
       if (nonNull(type)) {
           queries.put("type", type);
       }
       if (nonNull(filter)) {
           queries.put("filter", filter);
       }
       return queries;
   }
}

Hawa, soňky iki synpda talap döretmek üçin kartany taýýarlaýan populateQueries usulynyň bardygyny aýtmadym (soň görersiňiz). Aboveokarda beýan edilen sapaklara esaslanyp, JavaRushGroupClient üçin interfeýs döredeliň :

package com.github.javarushcommunity.jrtb.javarushclient;

import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupDiscussionInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupRequestArgs;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupsCountRequestArgs;

import java.util.List;

/**
 * Client for Javarush Open API corresponds to Groups.
 */
public interface JavaRushGroupClient {

    /**
     * Get all the {@link GroupInfo} filtered by provided {@link GroupRequestArgs}.
     *
     * @param requestArgs provided {@link GroupRequestArgs}.
     * @return the collection of the {@link GroupInfo} objects.
     */
    List<GroupInfo> getGroupList(GroupRequestArgs requestArgs);

    /**
     * Get all the {@link GroupDiscussionInfo} filtered by provided {@link GroupRequestArgs}.
     *
     * @param requestArgs provided {@link GroupRequestArgs}
     * @return the collection of the {@link GroupDiscussionInfo} objects.
     */
    List<GroupDiscussionInfo> getGroupDiscussionList(GroupRequestArgs requestArgs);

    /**
     * Get count of groups filtered by provided {@link GroupRequestArgs}.
     *
     * @param countRequestArgs provided {@link GroupsCountRequestArgs}.
     * @return the count of the groups.
     */
    Integer getGroupCount(GroupsCountRequestArgs countRequestArgs);

    /**
     * Get {@link GroupDiscussionInfo} by provided ID.
     *
     * @param id provided ID.
     * @return {@link GroupDiscussionInfo} object.
     */
    GroupDiscussionInfo getGroupById(Integer id);
}

GroupInfo ýa-da GroupDiscussionInfo maglumatlary goşmak islänimizde kazyýet işi üçin iki dürli haýyş. Otherwiseogsam, bu haýyşlar birmeňzeşdir we ýeke-täk tapawudy, biriniň arasynda “Diskussion” baýdagy dogry, beýlekisinde bolsa ýalan bolar. Şonuň üçin üç däl-de, 4 usul bardy. Indi durmuşa geçirip başlalyň:

package com.github.javarushcommunity.jrtb.javarushclient;

import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupDiscussionInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupRequestArgs;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupsCountRequestArgs;
import kong.unirest.GenericType;
import kong.unirest.Unirest;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.util.List;

/**
* Implementation of the {@link JavaRushGroupClient} interface.
*/
@Component
public class JavaRushGroupClientImpl implements JavaRushGroupClient {

   private final String javarushApiGroupPath;

   public JavaRushGroupClientImpl(@Value("${javarush.api.path}") String javarushApi) {
       this.javarushApiGroupPath = javarushApi + "/groups";
   }

   @Override
   public List<GroupInfo> getGroupList(GroupRequestArgs requestArgs) {
       return Unirest.get(javarushApiGroupPath)
               .queryString(requestArgs.populateQueries())
               .asObject(new GenericType<list<GroupInfo>>() {
               })
               .getBody();
   }

   @Override
   public List<GroupDiscussionInfo> getGroupDiscussionList(GroupRequestArgs requestArgs) {
       return Unirest.get(javarushApiGroupPath)
               .queryString(requestArgs.populateQueries())
               .asObject(new GenericType<list<GroupDiscussionInfo>>() {
               })
               .getBody();
   }

   @Override
   public Integer getGroupCount(GroupsCountRequestArgs countRequestArgs) {
       return Integer.valueOf(
               Unirest.get(String.format("%s/count", javarushApiGroupPath))
                       .queryString(countRequestArgs.populateQueries())
                       .asString()
                       .getBody()
       );
   }

   @Override
   public GroupDiscussionInfo getGroupById(Integer id) {
       return Unirest.get(String.format("%s/group%s", javarushApiGroupPath, id.toString()))
               .asObject(GroupDiscussionInfo.class)
               .getBody();
   }


}

Men eýýäm tanyş bolan Gymmat düşündirişini ulanyp, konstruktordaky API-ä ýol goşýaryn. Bu düşündirişiň içindäki bahanyň häsiýetler faýlyndaky meýdana laýyk gelýändigini aňladýar. Şonuň üçin, programma.properties-a täze setir goşalyň:

javarush.api.path=https://javarush.com/api/1.0/rest

Bu baha indi ähli API müşderileri üçin bir ýerde bolar we API ýoly üýtgese, ony çalt täzeläris. Mundan ozal dyrnaklary mikroskop bilen çekdim, “Unirest” -iň üsti bilen http haýyşyndan jogap aldym, ony setire terjime etdim we bu setiri Jeksonyň üsti bilen analiz etdim ... Bu gorkunç, ýadaw we köp goşmaça zatlar talap edýärdi. Bu kitaphanada onuň görnüşini görüp bilersiňiz. Elimi alanymdan soň, hemme zady üýtgederin. Indi sorag: kodumyz garaşyşymyz ýaly işleýärmi? Jogap aňsat: diňe olar üçin synag ýazmaly. Birnäçe gezek aýdyşym ýaly, döredijiler synag ýazmagy başarmaly. Şonuň üçin Swagger UI ulanyp, haýyşlar ibereris, jogaplara serederis we garaşylýan netije hökmünde synaglara çalşarys. Toparlaryň sanynyň statik däldigini we üýtgäp biljekdigini derrew gören bolmagyňyz mümkin. Dogry aýdýarsyňyz. Onlyeke-täk sorag, bu san näçe gezek üýtgeýär? Örän seýrek, şonuň üçin birnäçe aýyň dowamynda bu bahanyň statik boljakdygyny aýdyp bileris. Bir zat üýtgese, synaglary täzeläris. Tanyşmak - JavaRushGroupClientTest:

package com.github.javarushcommunity.jrtb.javarushclient;

import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupDiscussionInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupInfo;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupRequestArgs;
import com.github.javarushcommunity.jrtb.javarushclient.dto.GroupsCountRequestArgs;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.List;

import static com.github.javarushcommunity.jrtb.javarushclient.dto.GroupInfoType.TECH;

@DisplayName("Integration-level testing for JavaRushGroupClientImplTest")
class JavaRushGroupClientTest {

   private final JavaRushGroupClient groupClient = new JavaRushGroupClientImpl("https://javarush.com/api/1.0/rest");

   @Test
   public void shouldProperlyGetGroupsWithEmptyArgs() {
       //given
       GroupRequestArgs args = GroupRequestArgs.builder().build();

       //when
       List<GroupInfo> groupList = groupClient.getGroupList(args);

       //then
       Assertions.assertNotNull(groupList);
       Assertions.assertFalse(groupList.isEmpty());
   }

   @Test
   public void shouldProperlyGetWithOffSetAndLimit() {
       //given
       GroupRequestArgs args = GroupRequestArgs.builder()
               .offset(1)
               .limit(3)
               .build();

       //when
       List<GroupInfo> groupList = groupClient.getGroupList(args);

       //then
       Assertions.assertNotNull(groupList);
       Assertions.assertEquals(3, groupList.size());
   }

   @Test
   public void shouldProperlyGetGroupsDiscWithEmptyArgs() {
       //given
       GroupRequestArgs args = GroupRequestArgs.builder().build();

       //when
       List<GroupDiscussionInfo> groupList = groupClient.getGroupDiscussionList(args);

       //then
       Assertions.assertNotNull(groupList);
       Assertions.assertFalse(groupList.isEmpty());
   }

   @Test
   public void shouldProperlyGetGroupDiscWithOffSetAndLimit() {
       //given
       GroupRequestArgs args = GroupRequestArgs.builder()
               .offset(1)
               .limit(3)
               .build();

       //when
       List<GroupDiscussionInfo> groupList = groupClient.getGroupDiscussionList(args);

       //then
       Assertions.assertNotNull(groupList);
       Assertions.assertEquals(3, groupList.size());
   }

   @Test
   public void shouldProperlyGetGroupCount() {
       //given
       GroupsCountRequestArgs args = GroupsCountRequestArgs.builder().build();

       //when
       Integer groupCount = groupClient.getGroupCount(args);

       //then
       Assertions.assertEquals(30, groupCount);
   }

   @Test
   public void shouldProperlyGetGroupTECHCount() {
       //given
       GroupsCountRequestArgs args = GroupsCountRequestArgs.builder()
               .type(TECH)
               .build();

       //when
       Integer groupCount = groupClient.getGroupCount(args);

       //then
       Assertions.assertEquals(7, groupCount);
   }

   @Test
   public void shouldProperlyGetGroupById() {
       //given
       Integer androidGroupId = 16;

       //when
       GroupDiscussionInfo groupById = groupClient.getGroupById(androidGroupId);

       //then
       Assertions.assertNotNull(groupById);
       Assertions.assertEquals(16, groupById.getId());
       Assertions.assertEquals(TECH, groupById.getType());
       Assertions.assertEquals("android", groupById.getKey());
   }
}

Synaglar öňküsi ýaly stilde ýazylýar. Her haýyş üçin birnäçe synag bar. Hemme zady synagdan geçirmegiň manysy ýok, sebäbi bu API eýýäm iň gowy usulda synagdan geçirildi diýip pikir edýärin.

Netije

Bu makalanyň bir bölegi hökmünde, JavaRush API-ä toparlar üçin Java müşderisini goşduk. Aýdyşlary ýaly ýaşa we öwren. Bu müşderini ýazýarkam, resminamalaryndan peýdalandym we hödürleýän zatlary bilen işi amatly ulandym. Ünsüňizi teklip eden meselä çekýärin. Kimdir biri gyzyklanýan bolsa, maňa şahsy habar ýazyň, gaty gyzykly tejribe boljakdygyna has ynanýaryn. Bu birinji bölümdi. Ikinjisinde, goşmak buýrugyny gönüden-göni durmuşa geçireris we (bir makala gabat gelsek) ulanyjynyň ýazylan toparlarynyň sanawyny alarys. Ondan soň, bot üçin tekst ýazmak islegi we zehini bar, maňa PM-de ýazmagyňyzy haýyş edýärin. Men bu meselede hünärmen däl we islendik kömek gaty peýdaly bolardy. Bularyň hemmesini açyk çeşme ösüşi hökmünde resmileşdireliň, gyzykly bolar! Bolýar, hemişeki ýaly - abuna ýazyň, jaň ediň , taslamamyza ýyldyz beriň , teswir ýazyň we makalany baha beriň!

Tapgyryň ähli materiallarynyň sanawy bu makalanyň başynda.